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 · Русский · العربية

______________________________________________________________________

特性

______________________________________________________________________

运作原理

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. 设置一次 — npx @aitytech/agentkits-memory 配置您的平台
2. 自动捕获 --Hooks在您工作时记录决策、工具使用和摘要
3. 上下文注入 --下一节课从往届课的相关历史开始
4. 后台处理 --工作人员用人工智能丰富观察结果，生成嵌入，压缩旧数据
5. 随时搜索 --AI使用MCP工具(memory_search → memory_details)查找过去的上下文

所有数据都保留在 .claude/memory/memory.db 在你的机器上。没有云。不需要API密钥。

______________________________________________________________________

重要的设计决策

大多数内存工具将数据分散在markdown文件中，需要Python运行时，或者将代码发送到外部API。AgentKits Memory做出了根本不同的选择：

______________________________________________________________________

网络观众

通过现代网络界面查看和管理您的记忆。

npx @aitytech/agentkits-memory web

然后打开 http://localhost:1905 在您的浏览器中。

会话列表

使用时间线视图和活动详细信息浏览所有会话。

内存列表

通过搜索和命名空间过滤浏览所有存储的内存。

添加内存

使用键、名称空间、类型、内容和标签创建新的内存。

内存详情

使用编辑和删除选项查看完整内存详细信息。

管理嵌入

生成和管理语义搜索的向量嵌入。

______________________________________________________________________

快速开始

选项1:克劳德代码插件市场（建议用于克劳德代码）

只需一个命令即可作为插件安装——无需手动配置：

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

这将自动安装钩子、MCP服务器和内存工作流技能。安装后重新启动Claude Code。

选项2：自动设置（所有平台）

npx @aitytech/agentkits-memory

此自动检测您的平台并配置所有内容：MCP服务器、钩子（Claude Code/OpenCode）、规则文件（Cursor/Windsurf/Cline），并下载嵌入模型。

针对特定平台：

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

选项3：手动MCP配置

如果您更喜欢手动设置，请在MCP配置中添加：

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

配置文件位置：

• 克劳德代码: .claude/settings.json （嵌入 mcpServers 按键）
• 光标: .cursor/mcp.json
• 帆板运动: .windsurf/mcp.json
• Cline/OpenCode: .mcp.json （项目根）

3.MCP工具

配置后，您的AI助手可以使用这些工具：

______________________________________________________________________

渐进式披露（代币高效搜索）

AgentKits内存使用 三层搜索模式 与预先获取完整内容相比，这节省了约70%的令牌。

运作原理

┌─────────────────────────────────────────────────────────────┐
│  Step 1: memory_search                                      │
│  Returns: IDs, titles, tags, scores (~50 tokens/item)       │
│  → Review index, pick relevant memories                     │
└─────────────────────────────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 2: memory_timeline (optional)                         │
│  Returns: Context ±30 minutes around memory                 │
│  → Understand what happened before/after                    │
└─────────────────────────────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 3: memory_details                                     │
│  Returns: Full content for selected IDs only                │
│  → Fetch only what you actually need                        │
└─────────────────────────────────────────────────────────────┘

工作流示例

// Step 1: Search - get lightweight index
memory_search({ query: "authentication" })
// → Returns: [{ id: "abc", title: "JWT pattern...", score: 85% }]

// Step 2: (Optional) See temporal context
memory_timeline({ anchor: "abc" })
// → Returns: What happened before/after this memory

// Step 3: Get full content only for what you need
memory_details({ ids: ["abc"] })
// → Returns: Full content for selected memory

代币节省

______________________________________________________________________

CLI命令

# One-command setup (auto-detects platform)
npx @aitytech/agentkits-memory
npx @aitytech/agentkits-memory setup --platform=cursor   # specific platform
npx @aitytech/agentkits-memory setup --platform=all      # all platforms
npx @aitytech/agentkits-memory setup --force             # re-install/update

# Start MCP server
npx @aitytech/agentkits-memory server

# Web viewer (port 1905)
npx @aitytech/agentkits-memory web

# Terminal viewer
npx @aitytech/agentkits-memory viewer
npx @aitytech/agentkits-memory viewer --stats
npx @aitytech/agentkits-memory viewer --json

# Save from CLI
npx @aitytech/agentkits-memory save "Use JWT with refresh tokens" --category pattern --tags auth,security

# Settings
npx @aitytech/agentkits-memory hook settings .
npx @aitytech/agentkits-memory hook settings . --reset
npx @aitytech/agentkits-memory hook settings . aiProvider.provider=openai aiProvider.apiKey=sk-...

# Export / Import
npx @aitytech/agentkits-memory hook export . my-project ./backup.json
npx @aitytech/agentkits-memory hook import . ./backup.json

# Lifecycle management
npx @aitytech/agentkits-memory hook lifecycle . --compress-days=7 --archive-days=30
npx @aitytech/agentkits-memory hook lifecycle-stats .

______________________________________________________________________

程序化使用

import { ProjectMemoryService } from '@aitytech/agentkits-memory';

const memory = new ProjectMemoryService({
  baseDir: '.claude/memory',
  dbFilename: 'memory.db',
});
await memory.initialize();

// Store a memory
await memory.storeEntry({
  key: 'auth-pattern',
  content: 'Use JWT with refresh tokens for authentication',
  namespace: 'patterns',
  tags: ['auth', 'security'],
});

// Query memories
const results = await memory.query({
  type: 'hybrid',
  namespace: 'patterns',
  content: 'authentication',
  limit: 10,
});

// Get by key
const entry = await memory.getByKey('patterns', 'auth-pattern');

______________________________________________________________________

自动捕捉挂钩

Hooks会自动捕获您的AI编码会话（仅限Claude Code和OpenCode）：

设置挂钩：

npx @aitytech/agentkits-memory

自动捕获的内容：

• 带路径的文件读/写
• 代码更改为结构化差异（之前→ 之后）
• 开发人员意图（错误修复、功能、重构、调查等）
• 会议总结，包括决定、错误和下一步行动
• 会话内的多提示跟踪

______________________________________________________________________

多平台支持

• MCP服务器 适用于所有平台（通过MCP协议的内存工具）
• 钩子 在Claude Code和OpenCode上提供自动捕获
• 规则文件 教Cursor/Windsurf/Cline记忆工作流程
• 内存数据 始终存储在 .claude/memory/ （单一事实来源）

______________________________________________________________________

背景工作者

每次会话后，后台工作人员都会处理排队的任务：

工作进程在会话结束后自动运行。每位工人：

• 每次运行最多可处理200个项目
• 使用锁文件防止并发执行
• 5分钟后自动终止（防止僵尸）
• 最多检索3次失败的任务

______________________________________________________________________

AI提供者配置

AI富集使用可插拔的提供者。默认值为 claude-cli （不需要API密钥）。

选项1：环境变量

# OpenAI
export AGENTKITS_AI_PROVIDER=openai
export AGENTKITS_AI_API_KEY=sk-...

# Google Gemini
export AGENTKITS_AI_PROVIDER=gemini
export AGENTKITS_AI_API_KEY=AIza...

# OpenRouter (uses OpenAI-compatible format)
export AGENTKITS_AI_PROVIDER=openai
export AGENTKITS_AI_API_KEY=sk-or-...
export AGENTKITS_AI_BASE_URL=https://openrouter.ai/api/v1
export AGENTKITS_AI_MODEL=anthropic/claude-3.5-haiku

# Local Ollama (no API key needed)
export AGENTKITS_AI_PROVIDER=openai
export AGENTKITS_AI_BASE_URL=http://localhost:11434/v1
export AGENTKITS_AI_MODEL=llama3.2

# Disable AI enrichment entirely
export AGENTKITS_AI_ENRICHMENT=false

选项2：持久设置

# Saved to .claude/memory/settings.json — persists across sessions
npx @aitytech/agentkits-memory hook settings . aiProvider.provider=openai aiProvider.apiKey=sk-...
npx @aitytech/agentkits-memory hook settings . aiProvider.provider=gemini aiProvider.apiKey=AIza...
npx @aitytech/agentkits-memory hook settings . aiProvider.baseUrl=https://openrouter.ai/api/v1

# View current settings
npx @aitytech/agentkits-memory hook settings .

# Reset to defaults
npx @aitytech/agentkits-memory hook settings . --reset

优先： 环境变量覆盖settings.json。Settings.json会覆盖默认值。

______________________________________________________________________

生命周期管理

管理内存随时间的增长：

# Compress observations older than 7 days, archive sessions older than 30 days
npx @aitytech/agentkits-memory hook lifecycle . --compress-days=7 --archive-days=30

# Also auto-delete archived sessions older than 90 days
npx @aitytech/agentkits-memory hook lifecycle . --compress-days=7 --archive-days=30 --delete --delete-days=90

# View lifecycle statistics
npx @aitytech/agentkits-memory hook lifecycle-stats .

______________________________________________________________________

出口/进口

备份和恢复您的项目记忆：

# Export all sessions for a project
npx @aitytech/agentkits-memory hook export . my-project ./backup.json

# Import from backup (deduplicates automatically)
npx @aitytech/agentkits-memory hook import . ./backup.json

导出格式包括会话、观察、提示和摘要。

______________________________________________________________________

内存类别

______________________________________________________________________

存储

记忆存储在 .claude/memory/ 在您的项目目录中。

.claude/memory/
├── memory.db          # SQLite database (all data)
├── memory.db-wal      # Write-ahead log (temp)
├── settings.json      # Persistent settings (AI provider, context config)
└── embeddings-cache/  # Cached vector embeddings

______________________________________________________________________

CJK语言支持

AgentKits内存具有 自动CJK支持 用于中文、日文和韩文文本搜索。

零配置

当 better-sqlite3 如果已安装（默认），CJK搜索将自动工作：

import { ProjectMemoryService } from '@aitytech/agentkits-memory';

const memory = new ProjectMemoryService('.claude/memory');
await memory.initialize();

// Store CJK content
await memory.storeEntry({
  key: 'auth-pattern',
  content: '認証機能の実装パターン - JWT with refresh tokens',
  namespace: 'patterns',
});

// Search in Japanese, Chinese, or Korean - it just works!
const results = await memory.query({
  type: 'hybrid',
  content: '認証機能',
});

运作原理

• 原生SQLite：用途 better-sqlite3 为了获得最佳性能
• 三角图标记器：带有三元组的FTS5为CJK匹配创建3个字符序列
• 智能回退：短CJK查询（\

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

Give your AI assistant memory that persists.

AgentKits Memory by AityTech

Star this repo if it helps your AI remember.