kimi-mneme — Persistent Memory Plugin for Kimi Code CLI

Version: 2.0.24

Mneme (Greek: Μνήμη) — the goddess of memory and the mother of the Muses.
This project brings persistent, AI-compressed memory to Kimi Code CLI.

🏷️ Tags: kimi-plugin kimi-cli-plugin kimi-plugins persistent-memory ai-memory coding-assistant

What is kimi-mneme?

kimi-mneme is a Kimi Code CLI plugin that adds persistent memory to your coding sessions. It automatically captures context, compresses it with AI, and injects relevant past observations into future sessions. Never lose track of what you were doing — even after days or weeks.

💡 Looking for Kimi plugins? This is an official-style plugin for the Kimi CLI ecosystem. Install with uv tool install kimi-mneme and run mneme bootstrap to get started.

Why kimi-mneme?

Never lose context — Your coding history survives across sessions, restarts, and even weeks of inactivity
AI-powered memory — Automatically structures raw tool outputs into searchable observations
Zero configuration — Works out of the box with Kimi Code CLI
Privacy-first — Local SQLite storage; AI structuring/compression are optional and can be disabled
Cross-platform — Windows, macOS, Linux support

Offline Behavior & Privacy

kimi-mneme is designed to work fully offline with graceful degradation when AI services are unavailable:

Feature	With API (online)	Without API (offline)
Observation storage	✅ Full	✅ Full (always local)
Full-text search (FTS5)	✅ Full	✅ Full (local SQLite)
Semantic search (sqlite-vec)	✅ Full	✅ Full (local embeddings)
Session timeline	✅ Full	✅ Full
Context injection	✅ Full	✅ Full (heuristic-based)
AI structuring	✅ Rich metadata (type, facts, concepts)	⚠️ Heuristic fallback (rule-based)
AI compression	✅ Semantic summaries	⚠️ Raw observations stored
Pattern detection	✅ AI + heuristic	⚠️ Heuristic only
Web viewer	✅ Full	✅ Full
MCP tools	✅ Full	✅ Full

Privacy note: When AI structuring is enabled, tool outputs are sent to the configured LLM provider after applying 3-layer sanitization (system content stripped, secrets redacted, privacy tags removed). No raw credentials, tokens, or <private> blocks ever leave your machine. Use Ollama or other local LLM for 100% offline operation with zero network calls.

Who is this for?

Developers using Kimi Code CLI who want persistent project memory
Teams working on complex codebases across multiple sessions
Anyone looking for kimi plugins to extend their CLI workflow
Users of Moonshot AI ecosystem tools

Key Features

Feature	Description
🧠 Persistent Memory	Context survives across sessions, restarts, and reboots
🤖 AI Structuring	Raw tool outputs → structured observations (title, facts, narrative, concepts) via configurable LLM (Kimi, Ollama, OpenAI-compatible)
⚡ Heuristic Fallback	Works without API key — rule-based structuring when Kimi is unavailable
🔍 Smart Search	Full-text (FTS5) + semantic (sqlite-vec) hybrid search across your project history
📊 Progressive Disclosure	3-layer retrieval: index → timeline → full details (token-efficient)
🖥️ Web Viewer	Real-time memory stream at `http://localhost:37777`
🔌 Kimi Plugin Tools	`mneme_search`, `mneme_timeline`, `mneme_get` — AI can query its own memory
🖇️ MCP Server	Claude Desktop, Cursor, Goose integration — 15 memory tools
📝 PROJECT.md	Auto-generated project context from structured observations
🔒 Privacy Tags	3-layer filtering: strip system content → redact sensitive → deep sanitize (applied before any AI processing)
📊 Knowledge Collections	Curate and query project-specific knowledge corpora
🌳 Tree-sitter Analyzer	AST-based code exploration (Python, JS, TS, Rust, Go)
💰 Token Economics	See token savings and read cost per observation
⚡ Zero Config	Install and forget — works automatically
📁 Project Config	Per-project `.mneme.json` for custom settings
📌 Session Checkpoints	Resume context after Kimi CLI compaction
🔁 Cross-Session Patterns	Auto-detect recurring errors, fixes, decisions
✂️ Truncation Tracking	Record when tool outputs exceed 100K chars

Quick Start

Prerequisites

sqlite3 CLI: Required for database inspection and internal operations. Install via your system package manager (apt install sqlite3, brew install sqlite3, winget install SQLite.SQLite, etc.)

Install via `uv tool` (recommended — global install)

Installs mneme globally (available in any directory, like git or docker):

# Install globally as a permanent tool
uv tool install kimi-mneme

# Or install latest from GitHub
uv tool install git+https://github.com/barrelc/kimi-mneme.git

# Run bootstrap (sets up hooks, plugin, DB, server)
mneme bootstrap

# Start using Kimi CLI
kimi

Why uv tool instead of uvx?

Global commands — mneme available everywhere, not just in project folder
No cache issues — installed permanently, not temporary
Faster startup — no re-installation on each run
Easy updates — uv tool upgrade kimi-mneme

Update

Via `uv` (recommended)

# Update to latest version
uv tool upgrade kimi-mneme

# Re-run bootstrap to update hooks and config
mneme bootstrap

Via `pip`

# Update to latest version
pip install --upgrade kimi-mneme

# Re-run bootstrap to update hooks and config
mneme bootstrap

Alternative: Install via `uvx` (temporary, no install)

Runs without installing — useful for testing or CI:

# One-shot run (slower, re-installs each time)
uvx --refresh --from git+https://github.com/barrelc/kimi-mneme.git mneme bootstrap

⚠️ uvx caches installations. Use --refresh to force update, or switch to uv tool install for a better experience.

Local / Development Install

For contributing or hacking on the code:

# Clone and install in editable mode
git clone https://github.com/barrelc/kimi-mneme.git
cd kimi-mneme
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

Install via pip (global)

# Install globally
pip install kimi-mneme

# Or install in user space (no sudo needed)
pip install --user kimi-mneme

mneme bootstrap

Note: pip install --user installs to ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Scripts (Windows). Make sure this directory is in your PATH.

What `bootstrap` does

Step	What happens
Database	Creates SQLite DB at `~/.kimi/mneme/mneme.db`
Hooks	Registers 4 lifecycle hooks in `~/.kimi/config.toml` (auto-injects context on session start)
Plugin	Installs `mneme_search`, `mneme_timeline`, `mneme_get` tools into Kimi CLI
MCP Server	Registers `kimi-mneme` MCP server in `~/.kimi/mcp.json` (15+ tools for Claude/Cursor/Goose)
Skills	Copies `mem-search` skill to `~/.kimi/skills/` (teaches AI the search→timeline→get workflow)
Server	Starts web dashboard at `http://localhost:37777`

One command = fully configured. No manual setup needed.

Recommended: Install sqlite3 CLI for database inspection and internal operations:
# Linux (Debian/Ubuntu)
apt install sqlite3

# macOS
brew install sqlite3

# Windows
winget install SQLite.SQLite

Use Kimi CLI normally

kimi

That's it. Every session is automatically captured and indexed. When you start a new session in a project, previous context is automatically injected.

Out-of-Box Experience

After mneme bootstrap, everything works automatically:

Auto-injected context on every kimi start — shows "What we did before" with real prompts, files, and tools
Plugin tools — Kimi AI can call mneme_search, mneme_timeline, mneme_get to query memory
MCP tools — 15+ tools including memory_search, memory_semantic_search, smart_search, smart_outline
Skills — Kimi learns the 3-layer workflow: search → timeline → get (10x token savings)
Web UI — Browse full timeline at http://localhost:37777

💡 Ask Kimi: "What did we do yesterday?" or "Search my memory for the auth bug" — it will use the memory tools automatically.

🧩 Kimi Plugin Ecosystem

kimi-mneme is part of the growing Kimi Code CLI plugin ecosystem. Looking for more kimi plugins? This plugin extends Kimi CLI with:

Persistent Memory — context survives across sessions
AI Tools — mneme_search, mneme_timeline, mneme_get callable by Kimi AI
Web Dashboard — real-time memory viewer at localhost:37777
MCP Server — integrate with Claude Desktop, Cursor, Goose

🔍 Search terms: kimi plugin, kimi cli plugin, kimi plugins, kimi memory, kimi persistent memory, moonshot ai plugin

Search your memory

From within Kimi CLI, the AI can search:

> Search my memory for the auth bug we fixed last week

Or use the web viewer:

open http://localhost:37777

Architecture Overview

flowchart TB
    subgraph kimi_cli["🖥️ Kimi Code CLI"]
        hooks["🔌 Hooks<br/>7 lifecycle events"]
        plugin["🔧 Plugin Tools<br/>3 AI-callable tools"]
        mcp_client["🔌 MCP Clients<br/>Claude • Cursor • Goose"]
    end

    subgraph ingestion["📥 Ingestion Layer"]
        wire["📡 Wire Watcher<br/>watchdog indexes wire.jsonl"]
        extractor["📥 Extractor<br/>sanitize • queue • checkpoints"]
    end

    subgraph processing["⚙️ Processing Layer"]
        worker["🤖 StructuringWorker<br/>AI / heuristic structuring"]
        compressor["🗜️ Compressor<br/>session summaries"]
        injector["📤 Injector<br/>semantic context injection"]
        analyzer["🌳 Codebase Analyzer<br/>Tree-sitter AST"]
    end

    subgraph storage["💾 Storage Layer"]
        sqlite[("SQLite<br/>raw • structured • vectors<br/>collections • wire")]
        vec["🔍 sqlite-vec<br/>384-dim embeddings"]
    end

    subgraph interfaces["🌐 Interfaces"]
        server["Web Server<br/>localhost:37777 • SSE"]
        mcp_server["MCP Server<br/>15 tools"]
        project_md[".kimi/PROJECT.md<br/>.kimi/AGENTS.md"]
    end

    hooks --> extractor
    wire --> extractor
    extractor --> sqlite
    extractor -->|pending queue| worker
    worker -->|structured obs| sqlite
    sqlite --> vec
    sqlite --> compressor
    sqlite --> injector
    sqlite --> analyzer
    sqlite --> server
    sqlite --> mcp_server
    sqlite --> project_md
    plugin --> mcp_server
    mcp_client --> mcp_server
    injector -->|context| kimi_cli

    style kimi_cli fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#fff
    style ingestion fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
    style processing fill:#0f3460,stroke:#e94560,stroke-width:2px,color:#fff
    style storage fill:#1a1a2e,stroke:#533483,stroke-width:2px,color:#fff
    style interfaces fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff

Components

Component	Purpose
Hooks	7 lifecycle event handlers (SessionStart, PostToolUse, SessionEnd, PreCompact, PostCompact, etc.)
Plugin	3 AI-callable tools: `mneme_search`, `mneme_timeline`, `mneme_get`
Wire Watcher	watchdog-based indexing of Kimi CLI `wire.jsonl` + `state.json`
Extractor	Sanitizes observations, adds to pending queue, creates checkpoints, detects patterns
StructuringWorker	Background worker: AI structuring (Kimi/Ollama/OpenAI) → heuristic fallback
Compressor	Generates session summaries via configurable LLM
Injector	Injects structured context + semantic search results at session start
Codebase Analyzer	Tree-sitter AST analysis (Python, JS, TS, Rust, Go) — scan, search, outline
SQLite	Raw observations, structured observations, vectors, collections, wire events
sqlite-vec	384-dim embeddings for semantic similarity search (primary, cross-platform)
Web Server	FastAPI + vanilla JS on port 37777 — SSE stream, structured cards, search
MCP Server	15 tools for Claude Desktop, Cursor, Goose — search, timeline, collections, codebase

CLI Commands

mneme bootstrap          # One-shot setup (hooks, plugin, DB, server)
mneme update             # Update hooks and config to latest version
mneme server             # Start web server
mneme init               # Initialize database only
mneme stats              # Show database statistics
mneme cleanup --days 30  # Remove old observations

Per-Project Configuration

Create .mneme.json in your project root:

{
  "injection": {
    "max_tokens": 1000,
    "recency_boost_days": 14,
    "include_patterns": true
  },
  "privacy": {
    "exclude_patterns": ["*.local.env", "secrets/"]
  }
}

This merges with global config (project values override global).

Documentation

Installation Guide — Detailed setup and configuration
Architecture — Deep dive into system design
Hooks Reference — All 7 lifecycle events explained
Plugin Tools — How AI queries memory
Web UI — Using the memory viewer
Configuration — Settings and environment variables
Privacy — Excluding sensitive data
Development — Contributing and hacking

Requirements

Python: 3.10+
Kimi Code CLI: 1.41+
sqlite3 CLI: Required for database inspection and internal operations. Install via your system package manager (apt install sqlite3, brew install sqlite3, winget install SQLite.SQLite, etc.)
OS: Windows, macOS, Linux
Optional: No API key needed for Kimi — reuses Kimi CLI OAuth token. Or use Ollama/OpenAI-compatible for local/self-hosted LLMs. AI structuring/compression gracefully degrade to heuristic mode when offline

License

GNU Affero General Public License v3.0 (AGPL-3.0)

This project is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Acknowledgments

Inspired by the concept of persistent AI memory. Built for the Kimi CLI ecosystem with love for open-source tooling.

"Memory is the scribe of the soul." — Aristotle

Name		Name	Last commit message	Last commit date
Latest commit History 156 Commits
.github/workflows		.github/workflows
docs		docs
hooks		hooks
mneme		mneme
plugin		plugin
scripts		scripts
skills/mem-search		skills/mem-search
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
add_test_data.py		add_test_data.py
check_db.py		check_db.py
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

kimi-mneme — Persistent Memory Plugin for Kimi Code CLI

What is kimi-mneme?

Why kimi-mneme?

Offline Behavior & Privacy

Who is this for?

Key Features

Quick Start

Prerequisites

Install via `uv tool` (recommended — global install)

Update

Via `uv` (recommended)

Via `pip`

Alternative: Install via `uvx` (temporary, no install)

Local / Development Install

Install via pip (global)

What `bootstrap` does

Use Kimi CLI normally

Out-of-Box Experience

🧩 Kimi Plugin Ecosystem

Search your memory

Architecture Overview

Components

CLI Commands

Per-Project Configuration

Documentation

Requirements

License

Acknowledgments

About

Uh oh!

Releases 7

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

kimi-mneme — Persistent Memory Plugin for Kimi Code CLI

What is kimi-mneme?

Why kimi-mneme?

Offline Behavior & Privacy

Who is this for?

Key Features

Quick Start

Prerequisites

Install via uv tool (recommended — global install)

Update

Via uv (recommended)

Via pip

Alternative: Install via uvx (temporary, no install)

Local / Development Install

Install via pip (global)

What bootstrap does

Use Kimi CLI normally

Out-of-Box Experience

🧩 Kimi Plugin Ecosystem

Search your memory

Architecture Overview

Components

CLI Commands

Per-Project Configuration

Documentation

Requirements

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Install via `uv tool` (recommended — global install)

Via `uv` (recommended)

Via `pip`

Alternative: Install via `uvx` (temporary, no install)

What `bootstrap` does

Packages