🧠 kimi-mem

Persistent memory system for Kimi Code CLI.
Remember context across sessions. Never repeat yourself.

Inspired by claude-mem, built for the Kimi ecosystem.

---

✨ Features

• 🔁 Persistent Memory — Context survives across Kimi sessions
• 🪝 Native Hooks — Uses Kimi CLI's built-in lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd)
• 🤖 MCP Tools — 6 auto-search tools the agent can invoke during conversations
• 🔍 Full-Text + Semantic Search — SQLite FTS5 + sqlite-vec for hybrid retrieval
• 🎯 Progressive Disclosure — 3-layer retrieval: index → timeline → get
• 🧠 AI Summarization — Automatically compresses sessions into actionable memories via Moonshot API
• 🏷️ Tagged & Typed — Memories categorized as pattern, decision, bugfix, architecture, note
• 🔒 Privacy Tags — <private> blocks are automatically excluded from search/storage
• 🌐 Web Viewer — Local dashboard at http://localhost:37777
• 🌙 Token-Efficient — Injects only the most relevant memories, respects context limits
• ⚡ Zero External Services — SQLite is all you need; vector search included

---

📦 Installation

1. Install the package

pip install kimi-mem

# With web viewer support
pip install "kimi-mem[web]"

Or from source:

git clone https://github.com/theretech/kimi-mem.git
cd kimi-mem
pip install -e ".[web]"

2. Install hooks into Kimi CLI

Make sure kimi-mem is available in your PATH:

# If installed in a virtual environment, link the binary:
ln -s "$(pwd)/.venv/bin/kimi-mem" ~/.local/bin/kimi-mem

# Or install globally
pip install kimi-mem

Then install the hooks:

kimi-mem install

This appends hook entries to your ~/.kimi/config.toml.

🔄 Restart Kimi Code CLI for the hooks to take effect.

3. Install MCP server (optional, for auto-search)

kimi-mem mcp-install

This registers the kimi-mem MCP server so the agent can search memories automatically during conversations.

🔄 Restart Kimi Code CLI after installing MCP.

4. Set your API key (optional, for AI summarization)

export KIMI_API_KEY="your-moonshot-api-key"

If not set, kimi-mem still works — it just won't auto-summarize sessions with AI.

---

🚀 Quick Start

Let it run automatically

Once installed, kimi-mem works in the background:

1. Start a Kimi session → relevant memories are injected into context via additionalContext
2. Type a prompt → your question is saved to the session history
3. Use tools (ReadFile, Shell, etc.) → observations are captured silently
4. End the session → session is summarized with AI and memories are stored

The agent can also search memories on its own by calling MCP tools:

"What was that JWT fix we did last week?" → Agent auto-invokes kimi_mem_search

CLI Commands

# Search your memory (full-text)
kimi-mem search "authentication bug"

# Semantic search (vector)
kimi-mem search "how to handle jwt errors" --semantic

# Progressive disclosure
kimi-mem index "database migration"           # Layer 1: compact index
kimi-mem timeline <id>                        # Layer 2: chronological context
kimi-mem get <id>                             # Layer 3: full detail

# Recent memories
kimi-mem recent --limit 5

# Add a memory manually
kimi-mem add "Use jwt.ParseWithClaims for custom claims" \
  --type pattern --tag go --tag jwt

# Start web viewer
kimi-mem serve

# Check status
kimi-mem status

# MCP server (stdio transport)
kimi-mem mcp

---

🏗️ Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│  Kimi CLI   │────▶│   Hooks     │────▶│  kimi-mem core  │
│  (session)  │     │ (stdin JSON)│     │  (Python + SQLite)│
└─────────────┘     └─────────────┘     └─────────────────┘
       │                                            │
       │         ┌─────────────────┐                │
       │         │  MCP Server     │◄───────────────┘
       │         │  (6 tools)      │
       │         └─────────────────┘
       │
       ▼
┌─────────────────┐
│  SQLite + FTS5  │
│  + sqlite-vec   │
│  (sessions +    │
│   prompts +     │
│   observations +│
│   memories)     │
└─────────────────┘

Hooks used

Event	What it does
SessionStart	Creates session in DB + retrieves relevant memories → injects via additionalContext
UserPromptSubmit	Saves the user's prompt to the session history
PostToolUse	Captures tool calls/outputs as observations (skips low-value tools)
Stop / SessionEnd	Summarizes session with AI → stores compressed memories

MCP Tools

Tool	Purpose
kimi_mem_search	Full-text or semantic search over memories
kimi_mem_index	Layer 1: compact index (~50 tokens/result)
kimi_mem_timeline	Layer 2: chronological context around a memory ID
kimi_mem_get	Layer 3: full memory detail by ID
kimi_mem_recent	List recent memories
kimi_mem_add	Manually add a memory

Progressive Disclosure (3 layers)

Inspired by claude-mem, kimi-mem uses token-efficient layered retrieval:

Layer	Command	Tokens	Purpose
L1	kimi-mem index <query>	~50-100/result	Compact preview with IDs
L2	kimi-mem timeline <id>	~200-500/result	Chronological context around a memory
L3	kimi-mem get <id>	~500-1000/result	Full content + metadata

---

🔒 Privacy

kimi-mem respects your privacy:

• <private>...</private> tags in any content are automatically detected and excluded from search, vector index, and session injection
• Private memories are still stored (for your reference) but never retrieved automatically
• Heuristics detect secrets, passwords, and API keys in observations (without blocking library names like jsonwebtoken)
• Use --include-private to explicitly search private memories

---

⚙️ Configuration

Environment variables:

Variable	Description	Default
KIMI_API_KEY	Moonshot API key for summarization	—
KIMI_MEM_DATA_DIR	Where to store the SQLite DB	~/.kimi-mem
KIMI_MEM_DB_PATH	Direct path to SQLite file	~/.kimi-mem/memory.db
KIMI_MEM_MODEL	Model for summarization	moonshot-v1-8k
KIMI_MEM_EMBEDDING_MODEL	Model for embeddings	moonshot-v1-embedding
KIMI_MEM_EMBEDDING_DIM	Embedding dimension	1024

---

🛠️ Development

# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,web]"

# Run tests
pytest

# Lint
ruff check .

# Format
ruff format .

---

📋 Roadmap

• SQLite + FTS5 persistent storage
• Native Kimi CLI hooks (5 lifecycle hooks)
• AI-powered session summarization
• Semantic vector search (sqlite-vec)
• Progressive disclosure (3-layer retrieval)
• Web viewer dashboard
• Privacy tags (<private> exclusion)
• MCP server for auto agent search
• PyPI publication
• Cross-project memory linking
• Memory import/export
• Team/shared memory

---

🤝 Contributing

This is an early alpha built by the community for the community.
PRs, issues, and ideas are welcome!

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Submit a PR

---

📄 License

MIT — see LICENSE for details.

---

☕ Support

If you find kimi-mem useful, consider supporting the project:

PIX (Brazil):
54802231000148 — THE RETECH LTDA - EPP

---

Built with 🌙 by The Retech and friends.