Metadata-Version: 2.4
Name: kana-memory
Version: 0.0.1
Summary: Hierarchical memory for LLM agents that dreams: layered recall, offline consolidation, and a small learned System One traverser.
Keywords: llm,agents,memory,retrieval,consolidation
Author: Bala Mithran
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# kana

Memory for LLM agents, modelled on how people remember.

Storage is cheap; context is not. Kana never deletes a memory. It keeps every experience at several layers of resolution, from a one-line gist down to the raw trace, and pulls in only as much as the current step needs:

- **Think with the gist first.** Recall starts at the top layer and stops as soon as that is enough.
- **Dig when stuck.** When the agent makes no progress, recall walks down the hierarchy toward finer detail.
- **Dream.** Offline, Kana replays what happened, consolidates episodes into abstractions and skills, adds shortcuts to memories that turned out useful, and retrains its small System One traverser on which memories actually helped.

The goal is memory that gets cheaper with experience: fewer hops and fewer context tokens per task, without losing accuracy.

```bash
pip install kana-memory
```

```python
import kana

mem = kana.Memory("agent.db")
mem.add(event)                       # stored raw, never deleted
ctx = mem.recall(query, budget=800)  # walk layers, stop early when the gist suffices
mem.feedback(outcome)                # did the task succeed?
mem.dream()                          # consolidate, rewire, retrain
```

**Status:** planning. This release reserves the name; the API above is the target, not yet implemented. Part of an IIT Madras MTech thesis on adaptive memory for autonomous LLM agents.
