--- 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 = C0·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} } ```
