AgentKits Memory

AgentKits Memory

by AityTech

Persistent Memory System for AI Coding Assistants

Your AI assistant forgets everything between sessions. AgentKits Memory fixes that.
Decisions, patterns, errors, and context — all persisted locally via MCP.

Website • Docs • Quick Start • How It Works • Platforms • CLI • Web Viewer

English · 简体中文 · 日本語 · 한국어 · Español · Deutsch · Français · Português · Tiếng Việt · Русский · العربية

---

Features

Feature	Benefit
100% Local	All data stays on your machine. No cloud, no API keys, no accounts
Blazing Fast	Native SQLite (better-sqlite3) = instant queries, zero latency
Zero Config	Works out of the box. No database setup required
Multi-Platform	Claude Code, Cursor, Windsurf, Cline, OpenCode — one setup command
MCP Server	9 tools: save, search, timeline, details, recall, list, update, delete, status
Auto-Capture	Hooks capture session context, tool usage, summaries automatically
AI Enrichment	Background workers enrich observations with AI-generated summaries
Vector Search	sqlite-vec semantic similarity with multilingual embeddings (100+ languages)
Web Viewer	Browser UI to view, search, add, edit, delete memories
3-Layer Search	Progressive disclosure saves ~87% tokens vs fetching everything
Lifecycle Mgmt	Auto-compress, archive, and clean up old sessions
Export/Import	Backup and restore memories as JSON

---

How It Works

Session 1: "Use JWT for auth"          Session 2: "Add login endpoint"
┌──────────────────────────┐          ┌──────────────────────────┐
│  You code with AI...     │          │  AI already knows:       │
│  AI makes decisions      │          │  ✓ JWT auth decision     │
│  AI encounters errors    │   ───►   │  ✓ Error solutions       │
│  AI learns patterns      │  saved   │  ✓ Code patterns         │
│                          │          │  ✓ Session context        │
└──────────────────────────┘          └──────────────────────────┘
         │                                      ▲
         ▼                                      │
    .claude/memory/memory.db  ──────────────────┘
    (SQLite, 100% local)

1. Setup once — npx @aitytech/agentkits-memory configures your platform
2. Auto-capture — Hooks record decisions, tool usage, and summaries as you work
3. Context injection — Next session starts with relevant history from past sessions
4. Background processing — Workers enrich observations with AI, generate embeddings, compress old data
5. Search anytime — AI uses MCP tools (memory_search → memory_details) to find past context

All data stays in .claude/memory/memory.db on your machine. No cloud. No API keys required.

---

Design Decisions That Matter

Most memory tools scatter data across markdown files, require Python runtimes, or send your code to external APIs. AgentKits Memory makes fundamentally different choices:

Design Choice	Why It Matters
Single SQLite database	One file (memory.db) holds everything — memories, sessions, observations, embeddings. No scattered files to sync, no merge conflicts, no orphaned data. Backup = copy one file
Native Node.js, zero Python	Runs wherever Node runs. No conda, no pip, no virtualenv. Same language as your MCP server — one npx command, done
Token-efficient 3-layer search	Search index first (~50 tokens/result), then timeline context, then full details. Only fetch what you need. Other tools dump entire memory files into context, burning tokens on irrelevant content
Auto-capture via hooks	Decisions, patterns, and errors are recorded as they happen — not after you remember to save them. Session context injection happens automatically on next session start
Local embeddings, no API calls	Vector search uses a local ONNX model (multilingual-e5-small). Semantic search works offline, costs nothing, and supports 100+ languages
Background workers	AI enrichment, embedding generation, and compression run asynchronously. Your coding flow is never blocked
Multi-platform from day one	One --platform=all flag configures Claude Code, Cursor, Windsurf, Cline, and OpenCode simultaneously. Same memory database, different editors
Structured observation data	Tool usage is captured with type classification (read/write/execute/search), file tracking, intent detection, and AI-generated narratives — not raw text dumps
No process leaks	Background workers self-terminate after 5 minutes, use PID-based lock files with stale-lock cleanup, and handle SIGTERM/SIGINT gracefully. No zombie processes, no orphaned workers
No memory leaks	Hooks run as short-lived processes (not long-running daemons). Database connections close on shutdown. Embedding subprocess has bounded respawn (max 2), pending request timeouts, and graceful cleanup of all timers and queues

---

Web Viewer

View and manage your memories through a modern web interface.

npx @aitytech/agentkits-memory web

Then open http://localhost:1905 in your browser.

Session List

Browse all sessions with timeline view and activity details.

Memory List

Browse all stored memories with search and namespace filtering.

Add Memory

Create new memories with key, namespace, type, content, and tags.

Memory Details

View full memory details with edit and delete options.

Manage Embeddings

Generate and manage vector embeddings for semantic search.

---

Quick Start

Option 1: Claude Code Plugin Marketplace (Recommended for Claude Code)

Install as a plugin with one command — no manual configuration needed:

/plugin marketplace add aitytech/agentkits-memory
/plugin install agentkits-memory@agentkits-memory

This installs hooks, MCP server, and memory workflow skill automatically. Restart Claude Code after installation.

Option 2: Automated Setup (All Platforms)

npx @aitytech/agentkits-memory

This auto-detects your platform and configures everything: MCP server, hooks (Claude Code/OpenCode), rules files (Cursor/Windsurf/Cline), and downloads the embedding model.

Target a specific platform:

npx @aitytech/agentkits-memory --platform=cursor
npx @aitytech/agentkits-memory --platform=windsurf,cline
npx @aitytech/agentkits-memory --platform=all

Option 3: Manual MCP Configuration

If you prefer manual setup, add to your MCP config:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@aitytech/agentkits-memory", "server"]
    }
  }
}

Config file locations:

• Claude Code: .claude/settings.json (embedded in mcpServers key)
• Cursor: .cursor/mcp.json
• Windsurf: .windsurf/mcp.json
• Cline / OpenCode: .mcp.json (project root)

3. MCP Tools

Once configured, your AI assistant can use these tools:

Tool	Description
memory_status	Check memory system status (call first!)
memory_save	Save decisions, patterns, errors, or context
memory_search	[Step 1] Search index — lightweight IDs + titles (~50 tokens/result)
memory_timeline	[Step 2] Get temporal context around a memory
memory_details	[Step 3] Get full content for specific IDs
memory_recall	Quick topic overview — grouped summary
memory_list	List recent mem

---

README truncated. View full README on GitHub.