kokoro-memory

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

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.

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 (his voice) and 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:

Full collection: The Buddy Stack

License

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

Citation

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