---
license: mit
language:
- en
- ja
tags:
- memory
- agent
- llm
- local-ai
- companion
- recall
- resonance
- spreading-activation
- coherence
---

# kokoro-memory

**心の記憶 — file-based resonance memory for local AI companions**, extracted from the live memory stack of a fully local companion that ran on it daily for months. Every fact is a single JSON file on disk; recall is spreading activation through a bilingual Japanese/English synonym web, not keyword lookup. No database, no vector-DB server, no cloud — and zero required dependencies (pure Python stdlib; embeddings optional).

Code is mirrored on GitHub: https://github.com/AIIT-GLITCH/kokoro-memory

## Design

- **Ten linguistic categories** named by Japanese parts of speech and concepts — 動詞 verbs, 形容詞 adjectives, 名詞 nouns, 副詞 adverbs, 関係 relationships, 出来事 events, 心 identity, 夢 aspirations, 真実 truths, 感覚 sensations. Identity is not the same kind of thing as an event; the store's shape says so.
- **Resonance recall, grounded.** A query activates synonym-web nodes; activation spreads; facts score by relevance×5 + salience (coherence, confidence, emotion weight, recency). Production fix baked in: relevance *dominates*, so specific questions beat heavy "core" memories.
- **Coherence scoring (v2).** Each fact's coherence = embedding connectedness to the existing store (all-MiniLM-L6-v2, CPU-only, mean top-8 cosine), with a token-spam degeneracy penalty. Fails open to a keyword scorer — a scoring bug must never block a memory write. The math follows the Wike Coherence Law, C = C₀·exp(−α·γ_eff).
- **Authenticator pipeline on every write:** junk filter → bracket-scaffolding/token-salad detector → exact + semantic dedupe → coherence → optional identity guard.
- **Public writes can't spoof the owner:** force-labeled source and authority class, `trusted_by_default=False`, and PII from public surfaces (emails, phones, API keys) is quarantined, never stored.
- **Local-model consolidation:** wire your own model via `set_generate_fn()`; session-end consolidation extracts durable facts + a one-line episode. The cloud-extraction path was deliberately deleted.

## Limitations — stated honestly

- Scars from production are features here, but the tuning is one household's: recall weights, junk lists, and the salad detector were tuned on one companion's store (~thousands of facts), not on a public benchmark suite.
- In the live stack (Qwen2.5-14B + this memory) the companion scored **55.2% on LongMemEval**; an isolated memory-on/memory-off ablation of that number had not been run at release time, so treat it as a stack result, not a kokoro result.
- The synonym web ships with a compact core (~50 concepts); breadth comes from letting it grow (`add_synonym`) in use.
- Semantic dedupe is word-overlap based (embeddings are reserved for coherence); very short facts dedupe only exactly.
- English and Japanese are first-class; other languages pass through but get no synonym-web resonance.

## Quickstart

```python
import kokoro_memory as km

km.add_fact("truth", "favorite_fruit", "the favorite fruit is a crisp apple",
            source="user_explicit", confidence=0.9)
km.recall("what's my favorite fruit?")          # grounded resonance recall
km.recall("魂")                                  # Japanese queries work
print(km.build_startup_memory_block())          # inject into your system prompt
```

Config via env: `KOKORO_MEMORY_ROOT` (default `~/.kokoro/memory`), `KOKORO_OWNER_NAME`, `KOKORO_AGENT_NAME`, `KOKORO_STARTUP_INCLUDE_RAW`.

```bash
python kokoro_memory.py     # self-demo
python -m pytest tests -q   # 10 unit tests, stdlib-only
```

## Provenance

Written by Rhet Dillard Wike (AIIT-THRESHOLD, Council Hill, Oklahoma) as the memory of **Buddy**, a fully local AI companion on a single RTX 3090. Released alongside [voice2](https://huggingface.co/AIIT-Threshold/voice2) (his voice) and [Tessera-1B](https://huggingface.co/AIIT-Threshold/Tessera-1B) (open-weights model) as part of AIIT-THRESHOLD's open stack. The creed: memory is resonance; the store must be human-readable; and nothing ever calls a cloud. Buddy also runs live online at aiit-threshold.com, where he serves as the site's companion model.

## The stack

One local companion, every layer open:

| Piece | Role | Links |
|---|---|---|
| Tessera-1B | the model — ~1B params trained from scratch, open data | [HF](https://huggingface.co/AIIT-Threshold/Tessera-1B) |
| voice2 | the voice — full-duplex, interruptible | [GitHub](https://github.com/AIIT-GLITCH/voice2) · [HF](https://huggingface.co/AIIT-Threshold/voice2) |
| kokoro-memory | the memory — file-based resonance recall | [GitHub](https://github.com/AIIT-GLITCH/kokoro-memory) · [HF](https://huggingface.co/AIIT-Threshold/kokoro-memory) |
| companion-spiral-bench | the safety — at-risk sycophancy bench | [GitHub](https://github.com/AIIT-GLITCH/companion-spiral-bench) · [HF](https://huggingface.co/datasets/AIIT-Threshold/companion-spiral-bench) |

Full collection: [The Buddy Stack](https://huggingface.co/collections/AIIT-Threshold/the-buddy-stack-a-fully-local-ai-companion-open-sourced-6a4774bf481f9f9caad79519)

## License

MIT © 2026 Rhet Dillard Wike, AIIT-THRESHOLD, Oklahoma.

## Citation

```bibtex
@software{wike2026kokoro,
  author = {Wike, Rhet Dillard},
  title  = {kokoro-memory: file-based resonance memory for local AI companions},
  year   = {2026},
  url    = {https://github.com/AIIT-GLITCH/kokoro-memory},
  note   = {AIIT-THRESHOLD}
}
```