Kumiho Memory

📄 Paper: Graph-Native Cognitive Memory for AI Agents — formal belief-revision semantics for versioned memory (arXiv:2603.17244)

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

Status

Privacy invariant: every write path — session mining, commit mining, skill ingestion — and every LLM-bound packet passes the same per-atom PII/credential boundary. Credential-bearing atoms are dropped, never stored.

Stable (1.x) Follows semantic versioning — the documented public API is stable and breaking changes bump the major version. Latest release: 1.6.0 (2026-09-19) — Engage can decide what to deliver: opt-in judged delivery judges a wider candidate pool in one batched evaluation request and hands over only the memories that answer the query, instead of whatever ranked top (off by default; inert without a paid Kumiho Cloud tier, and the kumiho floor is unchanged). Before it: 1.5.1 (2026-09-18) — A correction says what it corrects: a kumiho_memory_reflect capture can carry revises, the kref of the memory it replaces, and becomes that memory's next revision instead of a second memory beside it (needs kumiho>=0.13.2; older SDKs store as before). See 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.
• Write-time ontology (0.10, on by default) — every consolidation is decomposed into a typed knowledge graph (entities / facts / decisions / events / actions / questions) with deterministic edges; recall consumes the structure via an entity-bridge join and a fact-recall leg, both strictly additive (structural evidence never displaces conversation evidence). Opt out with KUMIHO_MEMORY_ONTOLOGY=0.
• Decision Memory (0.11, opt-in) — a second, code-domain profile: mine git commits into decision nodes with rationale, verbatim evidence atoms, and {repo, commit, file, line} anchors, then ask why("why is this file like this?", file=...) mid-session. See the section below.
• 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.
• Judged delivery (opt-in, paid Kumiho Cloud) — engage judges a wider candidate pool in one batched evaluation request and delivers only the memories that answer the query (necessary-memory recall 0.55 → 0.93, precision 0.38 → 0.92), instead of delivering whatever ranked top. Inert and fallback-safe wherever the capability is absent. See below.
• 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 — 20 tools with default ontology enabled (24 with Decision Memory enabled), auto-discovered by the core kumiho MCP server (see table below).

Belief-grounded insight (available in 1.5.0)

For a question involving earlier decisions, request a bounded insight brief on that turn's first engage call:

{
  "query": "Should we revisit the deployment choice given our new constraints?",
  "limit": 5,
  "recall_mode": "summarized",
  "include_insights": true
}

The additional insight_brief gives the answering agent source-backed review prompts for changed premises, stored conflicts and prior decisions. It includes revision references, bounded evidence snippets and questions to check before applying a past belief. These are hypothesis prompts, not verified insights or accepted decisions. An answer can still be direct when no connection helps.

The flag adds no retrieval, model call or memory write. Existing recall settings still apply; context and default behavior are unchanged. Missing related sources stay explicitly missing, and no hypothesis is automatically persisted. Set the flag on the first recall: engage's existing duplicate guard still applies. Python callers with already-retrieved, authorized results can use from kumiho_memory.insight import build_insight_brief directly.

The same call also returns synthesis_request: bounded source summaries, current context/goals, and a JSON answer contract for the host model. Use kumiho_memory_validate_insight_response to check structure and citation membership; semantic correctness still needs review. No additional provider API is required. Include the flag on the first engage call because dedup is shared.

For learning across decisions, explicitly record record_experience and separate record_outcome observations. The keyless Dream State workflow is prepare_patterns -> host proposal -> store_pattern -> check_pattern before reuse (all tool names carry the kumiho_memory_ prefix). Proposals retain sources, conditions and counterexamples; changed premises trigger a stale review result. No automatic publishing or belief promotion occurs. Add include_learned_sources: true alongside include_insights: true to discover those separately stored experiences/patterns for the current answer; this adds bounded searches and current-source checks. See the workflow and limits, real-memory pilot, and second-paper research outline.

See the development plan for the current contract, answer-quality evaluation, outcome tracking and Dream State follow-up phases.

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

pip install kumiho-memory

Minimal example

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:

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):

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:

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:

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"})).

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):

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

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)):

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.

Judged delivery (context optimization, opt-in)

kumiho_memory_engage normally delivers whatever the search returned: limit memories (default 5), so retrieval rank also decides what enters the answering context. Measured on 40 queries over 50 candidates each, rank cannot carry that decision — 61 of 100 necessary memories sat outside the top 5, and the search score separated necessary from unnecessary at AUC 0.67. Judging the same pool in one batched evaluation request separates them at AUC 0.97: necessary-memory recall 0.55 → 0.93, precision 0.38 → 0.92, delivered count dynamic (0–47, median 3), and nothing delivered for a query whose pool held nothing relevant.

Enabled, engage recalls a wider candidate pool, asks the Kumiho server's Evaluate RPC two questions about each candidate — is it about the query's subject, does it state something usable in a direct answer — and delivers the memories that pass both. context, results, source_krefs and count are all built from the survivors, and so is the optional insight brief. Nothing is padded: zero delivered memories is a valid, intended answer. kumiho_memory_recall is unchanged.

Requires a paid Kumiho Cloud tier. Evaluate does not exist on self-hosted CE or on an SDK without kumiho.evaluate, and an unentitled tier is refused. Everywhere it is unavailable the feature is inert: engage restores the caller's original recall. If candidates were widened, this requires one extra recall at the original limit: a wide result's prefix can differ from the original ranking. Graph-expanded evidence is preserved. Pools above the RPC's 64-fragment limit also take this fallback without an evaluation request. After a refusal that will not change soon (no entitlement, no RPC) the requesting identity stops asking for 10 minutes; after a transient one (over limit, provider unavailable) for 1 minute. While backed off the recall is not widened either, so the unavailable case costs nothing.

A malformed value falls back to the default with one warning.

Per request, not per process. A host that serves several identities from one process cannot express "on" as an environment variable — the entitlement belongs to the caller, not to the deployment. For those, judged_delivery(enabled) from kumiho_memory.context_optimization is a context manager that decides the switch for the calling context only, and engage prefers it over KUMIHO_MEMORY_CONTEXT_OPT_ENABLED in either direction while it is in force; the remaining knobs still come from the environment. The hosted Kumiho connector sets it per request from the caller's Kumiho Cloud tier. Nothing sets it on the stdio path, where the environment alone decides exactly as it did before.

What is sent for evaluation — per candidate: the first SUMMARY_CHARS characters of its summary, plus title, memory type and the ISO day it was created, under an opaque positional id (c01, c02, …). Krefs, space paths, tags, tenant and user ids never leave the process, and delivery always uses the full memory — the cut is for the judge only (measured: judging 600 characters keeps recall, raises precision 0.88 → 0.95 and cuts evaluation tokens 36%).

What engage reports — one additive field, present only while the feature is enabled:

{"optimization": {"status": "applied", "candidates": 50}}
{"optimization": {"status": "fallback", "candidates": 5, "reason": "not_entitled"}}

When the evaluation response reports usage, engage also returns an allowlisted optimization.usage object and optimization.evaluation_status (ok, partial, or a known evaluation failure status). For example:

{"optimization":{"status":"applied","candidates":35,"evaluation_status":"ok","usage":{"provider_requests":1,"cached_fragments":0,"input_tokens":2100,"output_tokens":180}}}

These example values are illustrative, not benchmark results. input_tokens and output_tokens are evaluation-provider usage, not the host LLM's context tokens or engage's approx_tokens / approx_payload_tokens. cached_fragments counts fragments served from evaluation cache. A successful full cache hit reports zero provider requests and a positive cached-fragment count. The current server's provider_requests counts successfully decoded provider responses, not every attempt: zero alone cannot rule out a timed-out or failed provider call.

Missing or invalid counters are omitted, never invented as zero. Usage is also preserved on evaluation-response fallbacks; local skips and RPC exceptions have no reported usage. Partial evaluation usage may be incomplete. applied means selection was applied, not that every candidate was judged successfully. No server request/trace ID is supplied by the current evaluation contract, so this response does not fabricate one. Optional optimization.budget describes the monthly quota including reservations; it is not an invoice.

candidates is how many memories were judged (applied) or recalled (fallback); reason appears only on a fallback and is one of backoff, no_candidates, sdk_unavailable, not_entitled, over_limit, provider_unavailable, invalid_request, unknown_status, unimplemented, permission_denied, timeout, candidate_limit_exceeded, invalid_response, no_valid_judgments, error.

Supersession is deliberately not part of this: the judge keeps superseded "latest version" memories, which the existing deterministic supersession markers handle instead.

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):

…and classifies each Space:

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).

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):

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.

Decision Memory — the why-layer for a codebase (0.11, opt-in)

git is a lossless graph of what/when/who; it cannot hold the why. Decision Memory mines commits into typed decision nodes (title, decision, rationale, the why-question they answer), verbatim evidence atoms (measurements, review findings — quoted, never paraphrased), and git anchors. Code is never copied: anchors are {repo, commit_hash, file, line_range} pointers, and node identity is sha-free (title + author-date), so rebases and squashes converge instead of duplicating — the memory does not rot as history rewrites.

export KUMIHO_MEMORY_DECISIONS=1      # opt-in gate (default off; legacy KUMIHO_MEMORY_CODE still honored)
kumiho-memory code-ingest . --range HEAD~30..HEAD   # idempotent; re-runs cost zero LLM calls

result = await manager.code_why(
    "why is rerank_async a single-worker executor?",
    file="kumiho_memory/recall_rerank.py", line=420,
)
# → decisions with rationale + evidence chains + superseded_by status,
#   plus an inject-ready markdown context block

Key properties:

• Three query legs, lexicographic fusion — a deterministic anchor leg (file → decisions, zero search), a semantic leg, and an evidence-bridge leg. Anchor facts always outrank cross-encoder probabilities.
• Belief revision — a reversed decision is linked with SUPERSEDES, demoted in ranking, and always carries superseded_by; an agent never receives a reversed decision as the answer without seeing its replacement.
• Physical isolation — code nodes live in a dedicated {project}-decisions kumiho project; conversation recall is untouched by construction (and by test).
• Design doc: docs/DECISION_MEMORY_DESIGN.md. Live-verified on this repo's own history: "why is the executor single-worker?" answers with the actual offload commit and its concurrency measurement as evidence.

MCP Tools

20 tools with default ontology enabled (24 with KUMIHO_MEMORY_DECISIONS=1), auto-discovered by the core kumiho MCP server:

Modules

Roadmap

• 0.5.x — Graph-augmented recall, sibling filtering, recall dedup
• 0.6.x — Level-of-Evidence belief revision
• 0.9.x — Cognitive-recall pipeline consolidated into the SDK
• 0.10.x — Write-time ontology on by default (typed knowledge graph)
• 0.11.x — Decision Memory: git-anchored code-decision domain (current)
• next — Decision Memory Phase 2: agent-session mining, conversation↔code bridges, editor-hook auto-capture (see issue #43 / kumiho-plugins#10)
• 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.

Research

kumiho-memory is the client-side implementation of the memory architecture formalized in:

Graph-Native Cognitive Memory for AI Agents: Formal Belief Revision Semantics for Versioned Memory Architectures — Kumiho Inc. arXiv:2603.17244 (2026), cs.AI. https://arxiv.org/abs/2603.17244

The paper proves a correspondence between the AGM belief-revision framework and the operational semantics of a property-graph memory system — satisfying the basic AGM postulates (K*2–K*6) and Hansson's belief-base postulates (Relevance, Core-Retainment). That is the formal grounding for the consolidation and belief-revision behavior this package exposes on the Kumiho Cognitive Memory graph.

If you use kumiho-memory in academic work, please cite:

@misc{kumiho2026graphnative,
  title         = {Graph-Native Cognitive Memory for AI Agents: Formal Belief Revision Semantics for Versioned Memory Architectures},
  author        = {{Kumiho Inc.}},
  year          = {2026},
  eprint        = {2603.17244},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  doi           = {10.48550/arXiv.2603.17244},
  url           = {https://arxiv.org/abs/2603.17244}
}

Acknowledgments

• Hugh Kim (author of memory-bank) — for the independent full-module deep-dive review of v0.18.0 (2026-07-17): it cross-validated this package's measurement discipline from the outside, sharpened the read-path roadmap, and drove the security & reliability workstream (#99–#109). The best kind of peer review — adversarial in method, generous in intent.

License

MIT