Kiki Memory

Neuroscience-inspired persistent memory for Claude Code.

Give Claude a brain that remembers across sessions — organized like human memory, with spatial clustering, temporal decay, and spaced repetition.

中文文档

Architecture

CLAUDE.md  (Working Memory / Hippocampus)
  ├── Activity Stream    — fast encoding, logarithmic decay
  └── Protocol Reference — consolidation rules
                │
          session-end consolidation (sleep replay)
                │
                ▼
memory/  (Long-Term Storage / Neocortex)
  ├── MEMORY.md          — Hippocampal Index (retrieval routing)
  ├── project-a.md       — Semantic cluster (topic file)
  ├── project-b.md       — Semantic cluster (topic file)
  └── activity-log-archive.md — Compressed history

How It Works: 4 Phases

Phase 1: Encode (during tasks)

Log every task in real-time. Tag surprises with [!CRIT] or [!HIGH] for stronger encoding.

Phase 2: Consolidate (session end)

Extract reusable knowledge from activity log → topic files. Like sleep replay transferring hippocampal memories to neocortex.

Phase 3: Decay (day start)

Compress the activity stream logarithmically: today (full detail) → yesterday (summary) → this week (per-project) → this month (CRIT/HIGH only) → archive.

Phase 4: Strength Update (session end)

Track access frequency per topic file using Bjork's dual-strength model. Files accessed after a long gap get a bigger boost (FSRS desirable difficulty).

Neuroscience Foundations

Concept	Source	How We Use It
Method of Loci	Ancient mnemonic	Spatial organization — CLAUDE.md + memory/ directory as "rooms"
Temporal Context Model	Howard & Kahana, 2002	[<--follows] causal linking between events
Complementary Learning Systems	McClelland et al., 1995	Fast hippocampal encoding → slow neocortical consolidation
Dual Strength Theory	Bjork & Bjork, 1992	Storage Strength (SS) vs Retrieval Strength (RS) tracking
FSRS	Open-source SRS	Desirable difficulty — forgotten topics gain more when re-accessed
Surprise-Weighted Encoding	Prediction error theory	CRIT/HIGH events encoded more richly, decay more slowly

Installation

# Clone to your Claude Code skills directory
git clone https://github.com/juxiaoju/kiki--memory.git ~/.claude/skills/kiki-memory

Quick Start

After installation, start a Claude Code session and say:

/memory-init

Claude will:

1. Create a memory/ directory in your project's auto-memory path
2. Set up MEMORY.md as the retrieval index
3. Ask which projects you're working on and create topic files
4. Inject the working memory protocol into your CLAUDE.md

From then on, the system runs automatically:

• During work: Claude logs tasks to the activity stream
• Session end: Claude consolidates knowledge to topic files
• Next day: Claude compresses yesterday's logs

What You Customize vs What Stays Fixed

You customize (your content):

• Topic files — your projects, knowledge, traps
• Behavioral disciplines — lessons you discover through experience
• Infrastructure tables — your servers, ports, domains
• Activity logs — generated as you work

Protocol stays fixed:

• The 4-phase consolidation flow
• Logarithmic decay schedule
• Log entry format: - MM-DD | project | description | status | [!severity]
• SS/RS tracking formulas
• Surprise marker definitions

File Structure

kiki--memory/
├── SKILL.md                    # Main skill (loaded by Claude Code)
├── protocol/
│   ├── consolidation.md        # Phase 2 detailed reference
│   ├── temporal-compression.md # Phase 3 decay rules + examples
│   └── strength-tracking.md    # Phase 4 Bjork SS/RS formulas
├── templates/
│   ├── CLAUDE.md.template      # Working memory scaffold
│   ├── MEMORY.md.template      # Index scaffold
│   ├── topic-file.md.template  # Per-project scaffold
│   └── activity-log-archive.md.template
└── examples/
    ├── example-claude-md.md    # Filled-in CLAUDE.md
    ├── example-memory-md.md    # Filled-in MEMORY.md
    └── example-topic-file.md   # Filled-in topic file

Commands

Command	What It Does
/memory-init	Initialize the memory system for your project
/consolidate	Force a consolidation cycle mid-session
/memory-status	Show topic index, activity stream, and blockers

References

• Bjork, R. A., & Bjork, E. L. (1992). A new theory of disuse and an old theory of stimulus fluctuation. Learning processes to cognitive processes: Essays in honor of William K. Estes.
• Howard, M. W., & Kahana, M. J. (2002). A distributed representation of temporal context. Journal of Mathematical Psychology, 46(3), 269-299.
• McClelland, J. L., McNaughton, B. L., & O'Reilly, R. C. (1995). Why there are complementary learning systems in the hippocampus and neocortex. Psychological Review, 102(3), 419-457.

License

MIT