AgentKits Memory

{ "title": "AgentKits Memory: Local Persistent Memory for AI Coding Assistants", "body": "## Overview\n\nAgentKits Memory provides persistent, local memory for AI coding assistants so they retain decisions, patterns, errors, and context across sessions. All data stays on your machine in a single SQLite file. No cloud, no API keys required.\n\n## When to Use AgentKits Memory\n\nUse AgentKits Memory when you want an AI assistant to remember past decisions, patterns, errors, and context between coding sessions. It is ideal when you need a local, private memory system that does not send data to the cloud. It helps reduce token usage by fetching only relevant memory context instead of entire files. Use it when you need to share memory across multiple AI coding assistants including Claude Code, Cursor, Windsurf, Cline, and OpenCode.\n\n## Capabilities\n\nAgentKits Memory stores everything in a single SQLite file (memory.db) that stays 100% local on your machine. Setup requires zero configuration: no database or API keys needed. The system supports multiple platforms: Claude Code, Cursor, Windsurf, Cline, and OpenCode.\n\nThe MCP server provides 9 tools: memory_status, memory_save, memory_search, memory_timeline, memory_details, memory_recall, memory_list, memory_update, and memory_delete. Auto-capture hooks for Claude Code and OpenCode record decisions, tool usage, and session summaries automatically. AI enrichment via background workers generates summaries, facts, and concepts from observations.\n\nVector search uses a local ONNX model (multilingual-e5-small) for semantic similarity in 100+ languages. A 3-layer progressive search (search index to timeline to details) saves approximately 87% of tokens compared to fetching full content for every result. Lifecycle management handles auto-compress, archive, and delete of old sessions. You can export and import memories as JSON.\n\nA web viewer on port 1905 lets you browse, add, edit, and delete memories. CLI commands handle setup, server, viewer, save, settings, export/import, and lifecycle management. A programmatic API is available through the ProjectMemoryService class. CJK language support includes an automatic trigram tokenizer and optional Japanese word segmentation via lindera.\n\nBackground workers self-terminate after 5 minutes, use PID lock files, and handle SIGTERM/SIGINT gracefully. Hooks run as short-lived processes with no memory leaks or zombie processes.\n\n## Prerequisites\n\nYou need Node.js LTS version 18.x, 20.x, or 22.x (recommended). An MCP-compatible AI coding assistant is required: Claude Code, Cursor, Windsurf, Cline, or OpenCode. For non-LTS Node versions on Windows, you need Visual Studio Build Tools with the "Desktop development with C++" workload, or windows-build-tools, or Chocolatey with vctools.\n\n## Installation and Setup\n\n### Installation via Claude Code Plugin Marketplace\n\nRun the following commands in Claude Code:\n\n\n/plugin marketplace add aitytech/agentkits-memory\n/plugin install agentkits-memory@agentkits-memory\n\n\nThen restart Claude Code.\n\n### Automated Setup for All Platforms\n\nRun the automated setup command to auto-detect your platform and configure the MCP server, hooks, rules files, and download the embedding model:\n\n\nnpx @aitytech/agentkits-memory\n\n\nOptionally specify a platform with the --platform parameter. For example:\n\n\nnpx @aitytech/agentkits-memory --platform=cursor\nnpx @aitytech/agentkits-memory --platform=windsurf,cline\nnpx @aitytech/agentkits-memory --platform=all\n\n\nThe --platform parameter accepts claude-code, cursor, windsurf, cline, opencode, or all. If omitted, the platform is auto-detected. Use --force to re-install or update existing configuration.\n\n### Manual MCP Configuration\n\nAdd the following to your MCP config file:\n\njson\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@aitytech/agentkits-memory\", \"server\"]\n }\n }\n}\n\n\nPlace the config in the appropriate file for your platform:\n- Claude Code: .claude/settings.json (under the mcpServers key)\n- Cursor: .cursor/mcp.json\n- Windsurf: .windsurf/mcp.json\n- Cline/OpenCode: .mcp.json (project root)\n\nIf the MCP config file is placed in the wrong location, the tools will not be available to the AI assistant.\n\n## Using the MCP Tools\n\nThe MCP server provides 9 tools. The most common workflow uses the 3-layer progressive search.\n\n### 3-Layer Progressive Search\n\nThis search strategy saves approximately 87% of tokens by fetching only lightweight metadata first, then full content only for the memories you need.\n\nStep 1: Call memory_search with a query to get a lightweight index containing IDs, titles, tags, and scores. Each result uses approximately 50 tokens.\n\nStep 2 (optional): Call memory_timeline with an anchor ID to get temporal context plus or minus 30 minutes around that memory.\n\nStep 3: Call memory_details with selected IDs to get full content only for the memories you need.\n\n### Other MCP Tools\n\n- memory_status - Check the current status of the memory system.\n- memory_save - Save a new memory with content, category, and tags.\n- memory_recall - Recall memories by namespace or query.\n- memory_list - List all memories with optional filters.\n- memory_update - Update an existing memory.\n- memory_delete - Delete a memory by ID.\n\n## Configuring AI Provider for Enrichment\n\nAI enrichment generates summaries, facts, and concepts from observations automatically. You can configure the AI provider either through environment variables or persistent settings.\n\n### Configuring via Environment Variables\n\nSet AGENTKITS_AI_PROVIDER to openai, gemini, or leave it unset for claude-cli. Set AGENTKITS_AI_API_KEY to your API key (not needed for claude-cli or Ollama). Optionally set AGENTKITS_AI_BASE_URL for OpenAI-compatible providers such as OpenRouter, GLM, or Ollama. Optionally set AGENTKITS_AI_MODEL to specify a model, for example gpt-4o-mini, gemini-2.0-flash, or llama3.2. Set AGENTKITS_AI_ENRICHMENT=false to disable AI enrichment entirely.\n\nEnvironment variables override settings.json, and settings.json overrides defaults.\n\n### Configuring via Persistent Settings\n\nRun the following command to set the AI provider and API key persistently:\n\n\nnpx @aitytech/agentkits-memory hook settings . aiProvider.provider=openai aiProvider.apiKey=sk-...\n\n\nReplace openai with gemini or another provider as needed. Optionally set the base URL:\n\n\nnpx @aitytech/agentkits-memory hook settings . aiProvider.baseUrl=https://openrouter.ai/api/v1\n\n\nView current settings with:\n\n\nnpx @aitytech/agentkits-memory hook settings .\n\n\nReset to defaults with:\n\n\nnpx @aitytech/agentkits-memory hook settings . --reset\n\n\nIf AI enrichment is enabled but the provider is misconfigured (wrong API key, base URL, or model), enrichment will fail.\n\n## Saving Memories from the CLI\n\nSave a memory directly from the command line:\n\n\nnpx @aitytech/agentkits-memory save 'Use JWT with refresh tokens' --category pattern --tags auth,security\n\n\nThe --category parameter specifies a category such as pattern, decision, or error. The --tags parameter accepts comma-separated tags.\n\n## Lifecycle Management\n\nLifecycle management handles auto-compress, archive, and delete of old sessions. Run the lifecycle command:\n\n\nnpx @aitytech/agentkits-memory hook lifecycle . --compress-days=7 --archive-days=30\n\n\nThis compresses observations older than 7 days and archives sessions older than 30 days. Add --delete and --delete-days=90 to also auto-delete archived sessions older than 90 days:\n\n\nnpx @aitytech/agentkits-memory hook lifecycle . --compress-days=7 --archive-days=30 --delete --delete-days=90\n\n\nIf lifecycle delete is used without the --delete flag, archived sessions will not be removed. View statistics with:\n\n\nnpx @aitytech/agentkits-memory hook lifecycle-stats .\n\n\n## Export and Import\n\nExport memories to a JSON file:\n\n\nnpx @aitytech/agentkits-memory hook export . my-project ./backup.json\n\n\nImport memories from a JSON file (deduplicates automatically):\n\n\nnpx @aitytech/agentkits-memory hook import . ./backup.json\n\n\nThe export format includes sessions, observations, prompts, and summaries.\n\n## Web Viewer\n\nStart the web viewer on port 1905:\n\n\nnpx @aitytech/agentkits-memory web\n\n\nThen open http://localhost:1905 in your browser. The web viewer lets you browse, add, edit, and delete memories. Use --stats to show statistics in the terminal viewer, or --json to output data as JSON.\n\n## Programmatic Usage\n\nImport the ProjectMemoryService class from @aitytech/agentkits-memory:\n\njavascript\nimport { ProjectMemoryService } from '@aitytech/agentkits-memory';\n\n\nCreate an instance with a configuration object:\n\njavascript\nconst memory = new ProjectMemoryService({\n baseDir: '.claude/memory',\n dbFilename: 'memory.db'\n});\n\n\nThe baseDir parameter sets the directory for the memory database (default: .claude/memory). The dbFilename parameter sets the database file name (default: memory.db). Additional optional parameters include enableVectorIndex (default: false), dimensions (default: 384), cacheEnabled (default: true), cacheSize (default: 1000), and cacheTtl (default: 300000 ms).\n\nInitialize the memory system:\n\njavascript\nawait memory.initialize();\n\n\nStore an entry:\n\njavascript\nawait memory.storeEntry({\n key: 'auth-pattern',\n content: 'Use JWT with refresh tokens',\n namespace: 'patterns',\n tags: ['auth', 'security']\n});\n\n\nQuery memories:\n\njavascript\nconst results = await memory.query({\n type: 'hybrid',\n namespace: 'patterns',\n content: 'authentication',\n limit: 10\n});\n\n\nGet a memory by key:\n\njavascript\nconst entry = await memory.getByKey('patterns', 'auth-pattern');\n\n\n## CJK Language Support\n\nCJK search works automatically with better-sqlite3. Short queries of fewer than 3 characters fall back to LIKE search, which may be less accurate. For example, storing an entry with Japanese content and then querying with a Japanese term works automatically:\n\njavascript\nawait memory.storeEntry({\n key: 'auth-jp',\n content: '認証機能の実装パターン',\n namespace: 'patterns'\n});\nconst results = await memory.query({\n type: 'hybrid',\n content: '認証機能'\n});\n\n\nIf a CJK query is shorter than 3 characters, the trigram tokenizer cannot match, and the system falls back to LIKE search which may be less accurate. Advanced Japanese word segmentation requires an optional lindera-sqlite build.\n\n## Background Workers\n\nBackground workers process up to 200 items per run, retry failed tasks up to 3 times, and auto-terminate after 5 minutes. Workers use lock files to prevent concurrent execution. If background workers are killed abruptly, lock files may remain, but stale-lock cleanup handles this. The embedding subprocess has bounded respawn (maximum 2), pending request timeouts, and graceful cleanup. If the embedding subprocess crashes more than 2 times, it will not respawn.\n\n## Hooks\n\nHooks are only available for Claude Code and OpenCode. Other platforms use rules files to teach the workflow. Hooks run as short-lived processes, not long-running daemons, which prevents memory leaks or zombie processes.\n\n## Memory Storage Location\n\nMemory data is always stored in .claude/memory/ as the single source of truth regardless of platform. All data stays in .claude/memory/memory.db on your machine.\n\n## Performance Metrics\n\nThe vector search model achieves strong performance across multiple benchmarks. The multilingual-e5-small model scores 90.29% on STS benchmark, 80.85% on classification tasks, 90.54% on reranking, and 91.74% on retrieval tasks. The 3-layer progressive search saves approximately 87% of tokens. The system stores data 100% locally.\n\n## Failure Modes\n\nIf better-sqlite3 native binaries are missing on non-LTS Node versions, setup will fail. Install build tools to resolve this. Node.js LTS versions (18.x, 20.x, 22.x) have prebuilt binaries. Non-LTS versions (19, 21, 23) require build tools. For non-LTS Node on Windows, install Visual Studio Build Tools, windows-build-tools, or Chocolatey with vctools workload.\n\nIf the MCP config file is placed in the wrong location, tools will not be available to the AI assistant. If AI enrichment is enabled but the provider is misconfigured (wrong API key, base URL, or model), enrichment will fail. If background workers are killed abruptly, lock files may remain, but stale-lock cleanup handles this. If the embedding subprocess crashes more than 2 times, it will not respawn. If lifecycle delete is used without the --delete flag, archived sessions will not be removed. If a CJK query is shorter than 3 characters, the trigram tokenizer cannot match, and the system falls back to LIKE search which may be less accurate.\n\n## Complete Parameter Reference\n\n### CLI Parameters\n\n| Parameter | Meaning | Required |\n|-----------|---------|----------|\n| --platform | Target platform(s) for setup: claude-code, cursor, windsurf, cline, opencode, or all | No (auto-detected if omitted) |\n| --force | Re-install or update existing configuration | No |\n| --compress-days | Age in days after which observations are compressed | No (for lifecycle command) |\n| --archive-days | Age in days after which sessions are archived | No (for lifecycle command) |\n| --delete | Enable deletion of archived sessions (opt-in) | No |\n| --delete-days | Age in days after which archived sessions are deleted | No |\n| --category | Category for a saved memory (e.g., pattern, decision, error) | No (for save command) |\n| --tags | Comma-separated tags for a saved memory | No (for save command) |\n| --stats | Show statistics in terminal viewer | No |\n| --json | Output terminal viewer data as JSON | No |\n| --reset | Reset settings to defaults | No (for hook settings command) |\n\n### Environment Variables\n\n| Variable | Meaning | Required |\n|----------|---------|----------|\n| AGENTKITS_AI_PROVIDER | AI provider for enrichment: claude-cli, openai, gemini | No (defaults to claude-cli) |\n| AGENTKITS_AI_API_KEY | API key for the AI provider | No (not needed for claude-cli or Ollama) |\n| AGENTKITS_AI_BASE_URL | Base URL for OpenAI-compatible providers | No |\n| AGENTKITS_AI_MODEL | Model name for the AI provider | No |\n| AGENTKITS_AI_ENRICHMENT | Set to false to disable AI enrichment | No |\n\n### ProjectMemoryService Configuration\n\n| Parameter | Meaning | Required |\n|-----------|---------|----------|\n| baseDir | Directory for the memory database (default: .claude/memory) | No |\n| dbFilename | Database file name (default: memory.db) | No |\n| enableVectorIndex | Enable vector index (default: false) | No |\n| dimensions | Vector dimensions (default: 384) | No |\n| cacheEnabled | Enable embedding cache (default: true) | No |\n| cacheSize | Cache size (default: 1000) | No |\n| cacheTtl | Cache TTL in ms (default: 300000) | No |\n\n## Examples\n\n### Automated Setup for All Platforms\n\n\nnpx @aitytech/agentkits-memory --platform=all\n\n\nThis configures all platforms simultaneously.\n\n### 3-Layer Search Workflow\n\nCall memory_search('authentication') to get a lightweight index. Call memory_timeline('abc') to show temporal context. Call memory_details(['abc']) to fetch full content.\n\n### Saving a Memory from CLI\n\n\nnpx @aitytech/agentkits-memory save 'Use JWT with refresh tokens' --category pattern --tags auth,security\n\n\n### Export and Import\n\n\nnpx @aitytech/agentkits-memory hook export . my-project ./backup.json\nnpx @aitytech/agentkits-memory hook import . ./backup.json\n\n\n### Lifecycle Management\n\n\nnpx @aitytech/agentkits-memory hook lifecycle . --compress-days=7 --archive-days=30 --delete --delete-days=90\n\n\n### Programmatic Usage\n\njavascript\nimport { ProjectMemoryService } from '@aitytech/agentkits-memory';\nconst memory = new ProjectMemoryService({ baseDir: '.claude/memory' });\nawait memory.initialize();\nawait memory.storeEntry({ key: 'auth', content: 'Use JWT', namespace: 'patterns' });\nconst results = await memory.query({ type: 'hybrid', content: 'authentication' });\nconst entry = await memory.getByKey('patterns', 'auth');\n\n\n### CJK Search\n\nStore an entry with Japanese content, then query with a Japanese term. The system handles this automatically.\n\n### AI Provider via Environment Variables\n\n\nexport AGENTKITS_AI_PROVIDER=openai\nexport AGENTKITS_AI_API_KEY=sk-...\nexport AGENTKITS_AI_BASE_URL=https://openrouter.ai/api/v1\nexport AGENTKITS_AI_MODEL=anthropic/claude-3.5-haiku\n\n\n### Persistent AI Settings\n\n\nnpx @aitytech/agentkits-memory hook settings . aiProvider.provider=openai aiProvider.apiKey=sk-...\n\n\n### Web Viewer\n\n\nnpx @aitytech/agentkits-memory web\n\n\nThen open http://localhost:1905 in your browser." }