| --- |
| 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} |
| } |
| ``` |
|
|
