KMA·

hyperbolic agentic memory for LLMs

Memory that has
a shape.

$
pip install kleinian-memory
view source on github

scroll — watch the crowd become a tree

[ fig. 01 — flat vector memory ]

A bag of vectors retrieved by cosine similarity. A crowd — everyone looks a bit like everyone. No parents, no children, no why.

[ fig. 02 — the same memories in KMA ]

A Kleinian fracture. Memory nested in self-similar cells — coarse concepts hold finer ones, and radius is generality, all the way down.

[1] — why shape matters

Flat memory answers one question.
Agents ask four more.

Cosine similarity answers “what looks alike?” — necessary, but not sufficient for an agent reasoning over a growing, branching history. Hyperbolic space embeds trees with almost no distortion, where flat Euclidean space cannot.

capabilityflat vectorskma
Similarity recall
Hierarchy — parent / child / subtree
“More general than” (asymmetric)
Explainability — why was this recalled?
Auto-organization

[2] — how it works

A layer, not a replacement.

KMA sits between your embedder and your store. Any embedding model, any vector DB, any LLM host via MCP — the structural layer goes on top, at near-zero compute.

text ─▶ embedding (any model) ─▶ φ chart ─▶ point in a Poincaré ball ─▶ memory tree ─▶ store (any DB)
                                    │                    │
                          direction = meaning    radius = generality

[01]

Embed

Any model — OpenAI, Gemma, MiniLM. A deterministic hashing fallback keeps it dependency-free.

[02]

Project

A trained chart φ maps the embedding into an n-D Poincaré ball. Semantics set the direction; hierarchy sets the radius.

[03]

Place

The memory lands under its nearest concept automatically. No manual parenting, no schema up front.

[04]

Retrieve

A hybrid of cosine similarity, hyperbolic structure, recency and importance — returning the why alongside the what.

[3] — what’s inside

Working code, not a paper idea.

A trained projection that beats flat cosine on hierarchical retrieval in controlled tests, reproduced end-to-end on EmbeddingGemma + a live Pinecone index. 36 tests passing. Honest scope: the gain is on hierarchy — flat similarity is cosine’s home turf, and there we aim for parity.

kma/memory.py

AgenticMemory — add · search · get_context · forget, with auto-placement

kma/engine.py

embed → place → hybrid + ensemble retrieval, cached query snapshot

kma/geometry.py

the math heart: Poincaré-ball ops with learnable curvature

kma/manifold.py

self-organizing manifold — sub-linear routing, geodesic walk, folding

kma/retrievers.py

cosine / BM25 / hyperbolic voters + rank fusion with an evidence gate

kma/chart.py

the trainable projection φ and its objective

kma/extract.py

LLM fact extraction — distill turns into atomic memories

kma/mcp_server.py

MCP connector, so any LLM host can use KMA as live memory

[4] — quickstart

Two minutes to a memory
your agent can explain.

as an agent’s memory

$
pip install kleinian-memory
from kma.memory import AgenticMemory

mem = AgenticMemory()
mem.add("the user is building a travel app for hikers",
        scope={"user_id": "alice"})
mem.add("they prefer python and fastapi",
        scope={"user_id": "alice"})   # auto-placed

print(mem.get_context(
    "what backend should I scaffold?",
    scope={"user_id": "alice"},
))
# -> a compact, prompt-ready memory block,
#    rolled up with its ancestors

as an MCP server — claude desktop / claude code

{
  "mcpServers": {
    "kma-memory": { "command": "kma-mcp" }
  }
}

Exposes memory.add · search · get_context · forget · explain_address to any MCP-capable host.

honest scope

  • Use KMA when structure matters: agent memory, taxonomies, is-a retrieval, drill-down / roll-up, explainable recall.
  • Skip it for flat RAG, dedup, FAQ — there, an embedding + cosine + a vector DB is the right tool, and KMA adds nothing.
  • Results so far come from small, controlled experiments. Larger real-world hierarchies (WordNet, arXiv) are on the roadmap.