Metadata-Version: 2.4
Name: kumiho-memory
Version: 0.8.1
Summary: Universal memory provider for AI agents (Redis + Kumiho)
Author-email: Kumiho Clouds <support@kumiho.cloud>
Maintainer-email: Kumiho Clouds <support@kumiho.cloud>
License-Expression: MIT
Project-URL: Homepage, https://kumiho.io
Project-URL: Documentation, https://docs.kumiho.io
Project-URL: Repository, https://github.com/kumihoclouds/kumiho-python
Project-URL: Issues, https://github.com/kumihoclouds/kumiho-python/issues
Project-URL: Changelog, https://github.com/kumihoclouds/kumiho-python/blob/main/kumiho-memory/RELEASE_NOTES.md
Keywords: kumiho,memory,ai-agents,redis,cognitive-memory,summarization,conversational-ai,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: kumiho>=0.10.4
Requires-Dist: redis[hiredis]>=5.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.8.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: kumiho-memory[anthropic,openai]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"

# Kumiho Memory

---

## Client-side memory provider for AI agents — working memory, consolidation, and belief revision on the Kumiho Cognitive Memory graph

---

### Status

> **Beta (0.6.x)**
> Actively developed; the public API is stabilizing but may still change
> between minor versions.
> Latest release: `0.6.1` (2026-07-03) — fixes the mirrored evidence-tag
> carrier introduced in `0.6.0` (requires `kumiho>=0.10.1`).
> `0.6.0` (2026-07-02) introduced Level-of-Evidence belief revision:
> evidence grading, a corroboration-aware assessor, Dream State policy
> injection, evidence-weighted recall, and per-Space knowledge profiles.
> See [`RELEASE_NOTES.md`](RELEASE_NOTES.md) for the full history.

---

### What this package is

`kumiho-memory` is a **client-side memory provider**: it buffers working
memory in Redis, consolidates conversations into the Kumiho Cognitive
Memory graph, and layers belief-revision policy (evidence grading,
corroboration, deployment-controlled deprecation) on top — all without
requiring changes to the Kumiho server.

It is designed to be:

* Lightweight
* Model-agnostic
* Framework-agnostic
* Safe to use in local or sandboxed environments

### What this package is NOT

`kumiho-memory` is a client of the Kumiho graph, not the graph itself:

* ❌ It does not implement the graph store, hybrid search, or edge
  storage — that's the Kumiho server (`kumiho-server`), reached through
  the core `kumiho` SDK.
* ❌ It does not run its own consolidation server — `DreamState` and
  `SpaceProfiler` are library/CLI/MCP-invoked passes over the graph, not
  a standing service.

Within those bounds, this package **does** implement working-memory
buffering, LLM-based consolidation, offline consolidation (Dream State),
graph-augmented recall, and evidence-aware belief revision — all
client-side, no server changes required.

---

### Features

* **Working memory** — Redis-backed session buffering
  (`RedisMemoryBuffer`), proxy/auth-resilient.
* **Consolidation** — LLM summarization + PII redaction into versioned
  graph revisions (`UniversalMemoryManager.consolidate_session`).
* **Dream State** — offline consolidation pass: relevance assessment,
  deprecation (capped, published-protected), tag/metadata enrichment,
  relationship discovery. Accepts deployment policy via
  `extra_instructions`.
* **Graph-augmented recall** — multi-query reformulation + edge
  traversal + semantic fallback (`GraphAugmentedRecall`).
* **Sibling revision filtering** — BM25-light or embedding-based
  filtering of stacked-item history.
* **Auto-assessment** — background write-time screening
  (`create_llm_assessor`) with a heuristic pre-filter and graph novelty
  check before any LLM call.
* **Level-of-Evidence belief revision** — memories carry an evidence
  grade (`official` / `corroborated` / `single_source` / `unverified`);
  a corroboration-aware assessor grades claims automatically, recall
  reranks and badges by grade, and Dream State respects grade-aware
  deployment policy. See below for details.
* **Space profiles** — per-Space churn/evidence/stability signals
  classify each Space (`canonical` / `working` / `correspondence`) so
  extraction strategy can adapt per collection.
* **Skill ingest** — parse and version `SKILL.md` files and reference
  docs into the graph (`kumiho-memory ingest-skill`).
* **MCP tools** — 13 tool wrappers, auto-discovered by the core `kumiho`
  MCP server (see table below).

---

### Typical use cases

* Production memory backend for AI agents and MCP-compatible runtimes
* Multi-agent and collaborative AI systems that need shared, versioned
  long-term memory
* Applications that must weigh conflicting information by source
  credibility (news, claims, multi-source corroboration)

---

### Installation

```bash
pip install kumiho-memory
```

---

### Minimal example

```python
from kumiho_memory import RedisMemoryBuffer

memory = RedisMemoryBuffer()

memory.add_message(
    project="example",
    session_id="demo-session",
    role="user",
    content="Hello!"
)
```

> This example demonstrates **temporary, short-term buffering only**.
> It does not represent long-term memory persistence.

---

### Architectural note

`kumiho-memory` is one component within a larger, model-agnostic memory
architecture. Persistent storage, hybrid search, and edge/relationship
storage live in the Kumiho server (`kumiho-server`), reached through the
core `kumiho` SDK — this package never talks to the server directly.

Working-memory buffering, consolidation, offline lifecycle management
(Dream State, SpaceProfiler), and belief-revision policy are all
implemented **client-side, in this package**, calling the server only
through the standard SDK operations (create/read revisions, tags,
metadata, edges). No server changes are required for any feature in this
package, including the Level-of-Evidence subsystem below.

---

### Evidence levels

Memories can carry an **evidence grade** describing how trustworthy they
are. The grade is stored in two mirrored places:

| carrier | key / format | why |
|---|---|---|
| revision metadata | `evidence_level` (+ optional `source`, `confidence`) | canonical value, machine-readable |
| graph tag | `evidence:<level>` | tags get server-side time-range history → point-in-time audits |

When the carriers diverge (tag application is best-effort per-tag), the
**metadata value wins** — `parse_evidence(meta, tags)` implements this.

**Levels** (most → least trustworthy):

| level | meaning |
|---|---|
| `official` | explicit operator/ingest flag — never LLM-inferred; SHOULD be paired with the `published` tag so Dream State's deprecation protection applies |
| `corroborated` | ≥ N independent agreeing sources, none contradicting |
| `single_source` | identified source, no corroboration |
| `unverified` | everything else |

**Promotion / demotion state machine:**

- `unverified → single_source` — first stored occurrence with an identified `source`
- `single_source → corroborated` — an assessor finds ≥ N independent agreeing memories, none contradicting
- `* → official` — only via explicit flag (`evidence_level="official"` on ingest/consolidate/CLI), never LLM-inferred
- demotion — only via Dream State policy or explicit API, never silently at write time

**Usage:**

```python
from kumiho_memory import UniversalMemoryManager, evidence_tag, parse_evidence

manager = UniversalMemoryManager()

# Grade at ingest time — stashed in session metadata, applied at consolidation
await manager.ingest_message(
    user_id="u1",
    message="Acme announced record earnings.",
    evidence_level="official",
    source="press-release:acme",
)

# ...or explicitly at consolidation (overrides the ingest-time grade)
await manager.consolidate_session(
    session_id=session_id,
    evidence_level="corroborated",
    source="news:reuters",
)

# Recall results expose the grade when present
results = await manager.recall_memories("acme earnings")
results[0].get("evidence_level")  # "official"
```

CLI: `kumiho-memory ingest-skill doc.md --evidence-level official`

Grades are **only stamped when provided** — memories stored without an
evidence level keep their existing metadata and tag set unchanged, and
`parse_evidence` returns `None` for them (callers may treat that as
`unverified` via `DEFAULT_EVIDENCE_LEVEL`).

#### Evidence assessor (automatic grading)

`create_evidence_assessor` plugs into the write-time screening seat
(`UniversalMemoryManager(auto_assess_fn=...)`) and grades incoming
claims automatically:

| rule | condition | outcome |
|---|---|---|
| official pinning | claim contradicts a memory tagged `evidence:official` | stored `unverified`, conflict recorded in `conflicts_with`; the pinned belief is never revised |
| corroboration | ≥ N agreeing memories with **distinct** `source`s, none contradicting | `corroborated`, `memory_type` forced to `fact`, optional `SUPPORTS` edges to corroborators |
| single source | claim has an identified source, no corroboration | `single_source` |
| default | — | `unverified` |

The assessor **never emits `official`** — that grade stays operator-only.
Corroboration counting needs `source` metadata on the recalled memories,
so it only fires once sources are being written (see the schema section).

The bare `published` tag deliberately does **not** trigger pinning by
default — this codebase stamps `published` on virtually every stored
revision as its currency tag. Deployments that use `published` as a
curated marker can opt in:
`EvidencePolicy(official_tags=frozenset({"evidence:official", "published"}))`.

```python
from kumiho_memory import EvidencePolicy, create_evidence_assessor

assessor = create_evidence_assessor(
    adapter,
    policy=EvidencePolicy(min_corroboration=2, create_supports_edges=True),
)
manager = UniversalMemoryManager(auto_assess_fn=assessor)
```

MCP env wiring: `KUMIHO_EVIDENCE_ASSESSOR=1` (takes precedence over
`KUMIHO_AUTO_ASSESS` when both are set), `KUMIHO_EVIDENCE_MIN_CORROBORATION`
(default 2), `KUMIHO_EVIDENCE_SUPPORTS_EDGES=1` for evidence-chain edges.
`SUPPORTS` edges are followed by graph-augmented recall (included in the
default `GraphAugmentationConfig.edge_types`).

#### Dream State deployment policy

Dream State's assessment prompt accepts deployment-specific policy via
`extra_instructions` — appended under a fenced `## DEPLOYMENT POLICY`
section. Three injection routes (precedence: explicit arg > env var;
pass `""` to explicitly disable the env policy):

```python
DreamState(extra_instructions="Never propose deprecation for memories "
                              "tagged evidence:official. Prefer deprecating "
                              "unverified duplicates over corroborated ones.")
```

```bash
kumiho-memory dream --policy "Never propose deprecation for memories tagged evidence:official."
export KUMIHO_DREAM_EXTRA_INSTRUCTIONS="..."   # fallback when no arg given
```

The MCP tool `kumiho_memory_dream_state` accepts the same text via its
`extra_instructions` argument. Each memory in the assessment payload
carries its `evidence_level` and policy-relevant `revision_tags`
(`published`, `evidence:*`) so the policy has data to act on.

**Hard guardrails are not overridable by policy** — they apply in code
*after* the LLM's suggestions: the `max_deprecation_ratio` cap,
published-revision protection (`allow_published_deprecation=False`), and
the conservative-KEEP rule (the core prompt states it takes precedence
over deployment policy). Run results and the Markdown report record the
active policy text for auditability.

#### Evidence-weighted recall (reranking + badges)

Server-side hybrid search ranks by relevance only — a rumor can outrank
an official statement. `kumiho-memory` adjusts scores client-side with a
deterministic delta per grade (no extra LLM calls, O(k)):

| grade | default delta |
|---|---|
| `official` | **+0.15** |
| `corroborated` | +0.08 |
| `single_source` | 0.0 |
| `unverified` | **−0.10** |

**Before/after example** — query returns `rumor (0.60, unverified)` and
`statement (0.50, official)`: unweighted order is `rumor, statement`;
weighted order is `statement (0.65), rumor (0.50)`.

Applied in both plain recall and graph-augmented recall (before each
result cap, idempotently — the original score is kept in the documented `base_score` result field).
**Default ON**, with a strict no-op guarantee: when no retrieved memory
carries a grade, results are byte-identical to previous behavior.
Kill switch: `KUMIHO_EVIDENCE_RERANK=0`. Library use:
`UniversalMemoryManager(evidence_rank=EvidenceRankConfig(...))`.

**Context badges** — `build_recalled_context` (used by
`kumiho_memory_engage`) prefixes graded memories so the answering model
can weigh sources: `[official] Acme Q2: record earnings...`,
`[unverified] Forum post: ...`. `single_source`/ungraded memories get no
badge. `kumiho_memory_recall` returns raw dicts — there the grade
surfaces as the `evidence_level` field instead of a text badge.

Note: `min_score` filtering (`KUMIHO_MEMORY_MIN_RELEVANCE_SCORE`)
applies to the **adjusted** score — an `unverified` memory sitting just
above the threshold can drop below it. That is the intended screening
behavior; use the `base_score` result field if you need the raw retrieval score.

#### Space profiles (per-collection extraction strategy)

A collection's observed dynamics are a signal about what kind of
knowledge lives in it. `SpaceProfiler` aggregates per-Space statistics
from existing SDK queries (pure aggregation, **no LLM**):

| signal | source |
|---|---|
| churn | revisions per item, revision rate in the window (`latest` tag-move proxy), SUPERSEDES chain depth |
| evidence histogram | `evidence_level` metadata per revision |
| deprecation ratio | `deprecated` flags on items/revisions |
| stability | published share, median revision age |

…and classifies each Space:

| label | meaning | thresholds |
|---|---|---|
| `canonical` | established concepts | stability ≥ 0.6, churn ≤ 0.4, and evidence ≥ 0.3 when any revision carries a grade (ungraded corpora are not penalized) |
| `correspondence` | claims / requests / responses | churn ≥ 0.6 and stability ≤ 0.4 |
| `working` | active projects/notes | everything else |

Stability and evidence describe the **live** (non-deprecated) revisions
only; churn counts historical stacking. Empty spaces are not classified
or persisted — "no data" is not a label.

The profile persists as a `kind="space-profile"` Item — one per Space,
one revision per run, with `SUPERSEDES` edges linking runs so profile
drift is itself a versioned chain. A Space owner pins the label with the
`space_class` Space attribute; the profiler then never relabels, and
instead reports pin/observation disagreement as drift (the observed
label is persisted alongside the pin as `observed_label`).

```bash
kumiho-memory profile --dry-run          # classify without persisting
kumiho-memory profile --window-days 14
```

MCP tool: `kumiho_memory_space_profile`. Read side for strategy
consumers (assessor / Dream State policy / recall):

```python
from kumiho_memory import get_space_profile

profile = get_space_profile("CognitiveMemory", "/CognitiveMemory/news")
if profile and profile.label == "correspondence":
    # e.g. store claims as events, never promote to fact
    ...
```

The extraction rule this enables: **in `correspondence` spaces, claims
are events, not facts** — store them attributed ("X claimed Y on DATE")
and raise corroboration thresholds, instead of promoting them into the
belief set. (Consumption hooks land with the assessor/Dream State/recall
pieces of the epic; the profiler + `get_space_profile` are the
foundation.)

Note: true `latest` tag-move counting is not possible client-side (the
SDK exposes point-in-time tag resolution, not tag-move events) —
revision-creation frequency is the documented proxy, valid because
`latest` moves on every `create_revision`.

---

### MCP Tools

13 tool wrappers, auto-discovered by the core `kumiho` MCP server:

| Tool | Description |
| ------ | ------------- |
| `kumiho_chat_add` | Add message to Redis working memory |
| `kumiho_chat_get` | Retrieve session messages |
| `kumiho_chat_clear` | Clear session working memory |
| `kumiho_memory_ingest` | Buffer message + recall context |
| `kumiho_memory_add_response` | Add assistant response to buffer |
| `kumiho_memory_consolidate` | Summarize, redact, store to graph |
| `kumiho_memory_recall` | Semantic search with dedup guard |
| `kumiho_memory_discover_edges` | Link new memory to related memories |
| `kumiho_memory_store_execution` | Store tool/command results |
| `kumiho_memory_engage` | Recall + build context in one call |
| `kumiho_memory_reflect` | Buffer response + store captures |
| `kumiho_memory_dream_state` | Run Dream State consolidation cycle |
| `kumiho_memory_space_profile` | Profile each Space's knowledge dynamics |

---

### Modules

| Module | Public API |
| -------- | ------------ |
| `memory_manager` | `UniversalMemoryManager`, `AutoAssessFn`, `MemoryAssessResult`, `get_memory_space` |
| `redis_memory` | `RedisMemoryBuffer` |
| `summarization` | `MemorySummarizer`, `LLMAdapter`, `EmbeddingAdapter`, `OpenAICompatAdapter`, `OpenAICompatEmbeddingAdapter`, `AnthropicAdapter` |
| `privacy` | `PIIRedactor`, `CredentialDetectedError` |
| `retry` | `RetryQueue` |
| `dream_state` | `DreamState`, `MemoryAssessment`, `DreamStateStats` |
| `graph_augmentation` | `GraphAugmentedRecall`, `GraphAugmentationConfig` |
| `assessors` | `create_llm_assessor`, `create_evidence_assessor`, `EvidencePolicy`, `grade_evidence`, `heuristic_prefilter`, `DEFAULT_STORAGE_POLICY` |
| `evidence` | `evidence_tag`, `parse_evidence`, `OFFICIAL`, `CORROBORATED`, `SINGLE_SOURCE`, `UNVERIFIED`, `EVIDENCE_LEVELS`, `DEFAULT_EVIDENCE_LEVEL` |
| `evidence_rank` | `apply_evidence_weights`, `evidence_badge`, `EvidenceRankConfig` |
| `space_profiler` | `SpaceProfiler`, `SpaceProfile`, `SpaceSignals`, `get_space_profile`, `SPACE_CLASSES` |
| `skill_ingest` | `ingest_skill`, `ingest_file`, `ingest_batch`, `parse_skill` |
| `mcp_tools` | `MEMORY_TOOLS`, `MEMORY_TOOL_HANDLERS` |

---

### Roadmap

* `0.5.x` — Graph-augmented recall, sibling filtering, recall dedup
* `0.6.x` — Level-of-Evidence belief revision (current)
* `1.0.0` — Stabilized public API, production-ready client SDK

The scope of this package will remain limited to **client-side concerns**
— no kumiho-server changes are required by anything on this roadmap.

---

### License

MIT
