AI导哈

LLM记忆与上下文引擎

MemoryClaw是一款为AI代理提供持久化记忆和智能上下文管理的开源库，支持跨会话记忆存储、检索和管理。

  • by tostechbr
  • TypeScript
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 tostechbr/akashic-context

使用说明

记忆爪

LLM的通用内存和上下文引擎

“MemoryClaw”意味着你的AI有一个通用的、无限的上下文。

MemoryClaw是一个开源库，它添加了 持久内存 和 智能上下文管理 AI代理。您的代理可以记住会话中过去的对话、决策和上下文，同时自动管理令牌限制。

愿景

┌─────────────────────────────────────────────────────────────┐
│                      MEMORYCLAW                     │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Memory    │  │   Context   │  │   Session   │         │
│  │   Search    │  │  Management │  │  Lifecycle  │         │
│  │  (Phase 1)  │  │  (Phase 2)  │  │  (Phase 3)  │         │
│  │     ✅      │  │     🚧      │  │     📋      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  Store memories → Search intelligently → Manage limits     │
└─────────────────────────────────────────────────────────────┘

当前状态：第1阶段-内存搜索✅ + Sprint 0下一步

今天有效的方法：

  • 将记忆存储在Markdown文件中（人类可读，git友好）
  • 使用BM25关键字匹配进行搜索
  • 通过MCP协议进行完整的CRUD操作（搜索、获取、存储、删除）
  • 压缩大文件以获得更好的搜索结果
  • 通过140项测试（单元+集成+QA）

⚠️ 电流限制： 没有多用户隔离。所有用户共享同一个工作区。 Sprint 0（下一个） 将添加 userId 所有工具的参数，用于每个用户的内存隔离。

Sprint 0即将发布： 多用户隔离（每个工具、每个用户数据库的用户ID）

进入第二阶段： 矢量搜索（sqlite-vec，混合合并）

进入第三阶段： 上下文管理（压缩、内存刷新、修剪）

n8n快速入门

1.克隆和构建

git clone https://github.com/tostechbr/memory-claw.git
cd memory-claw
pnpm install
pnpm build

2.创建记忆文件

my-workspace/
├── MEMORY.md           # Long-term curated knowledge
└── memory/
    ├── 2026-01-31.md   # Daily notes
    ├── projects.md     # Project notes
    └── contacts.md     # Important contacts

示例 MEMORY.md:

# My Memory

## About Me
I'm a developer working on AI projects.

## Current Projects
- MemoryClaw - Adding memory to AI agents
- My App - A productivity tool

## Important Contacts
- John: john@email.com - Technical mentor
- Sarah: sarah@email.com - Design partner

3.安装n8n社区节点

重要： 此集成使用 n8n节点mcp 社区节点，必须单独安装。

在n8n实例中：

  1. 首选 设置 → 社区节点
  2. 点击 安装社区节点
  3. 输入： n8n-nodes-mcp
  4. 点击 安装
  5. 安装后重新启动n8n

文档： https://www.npmjs.com/package/n8n-nodes-mcp

4.配置MCP服务器

编辑 packages/mcp-server/run-server.sh 指向您的工作区：

WORKSPACE="/path/to/your/my-workspace"

在n8n中创建MCP凭据：

  1. 首选 凭证 → 创建新
  2. 搜索“MCP”并选择 MCP API
  3. 填写以下字段：
字段 值
姓名 MemoryClaw
指挥部 bash
论点 /absolute/path/to/memory-claw/packages/mcp-server/run-server.sh
环境 OPENAI_API_KEY=sk-your-actual-key
  1. 点击 保存

重要提示： 使用 绝对路径 到 run-server.sh。相对路径将不起作用。

5.导入工作流程

在n8n中创建一个新的工作流并导入此JSON：

{
  "name": "MemoryClaw Memory Test",
  "nodes": [
    {
      "parameters": {
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.chatTrigger",
      "typeVersion": 1.1,
      "position": [460, 240],
      "id": "chat-trigger",
      "name": "When chat message received"
    },
    {
      "parameters": {
        "promptType": "define",
        "text": "={{ $json.chatInput }}",
        "options": {
          "systemMessage": "You are a personal assistant with access to the user's memory. Use the memory_search tool to find relevant information before answering questions."
        }
      },
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 1.7,
      "position": [680, 240],
      "id": "ai-agent",
      "name": "AI Agent"
    },
    {
      "parameters": {
        "model": "gpt-4o-mini"
      },
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1,
      "position": [680, 440],
      "id": "openai-model",
      "name": "OpenAI Chat Model",
      "credentials": {
        "openAiApi": {
          "id": "your-openai-credential",
          "name": "OpenAI account"
        }
      }
    },
    {
      "parameters": {
        "operation": "executeTool",
        "toolName": "memory_search",
        "toolParameters": "{\"query\": \"{{ $json.chatInput.replace(/\\n/g, ' ').trim() }}\", \"minScore\": 0}"
      },
      "type": "n8n-nodes-mcp.mcpClientTool",
      "typeVersion": 1,
      "position": [680, 80],
      "id": "mcp-client",
      "name": "MCP Client",
      "credentials": {
        "mcpApi": {
          "id": "your-mcp-credential",
          "name": "MemoryClaw"
        }
      }
    }
  ],
  "connections": {
    "When chat message received": {
      "main": [[{ "node": "AI Agent", "type": "main", "index": 0 }]]
    },
    "OpenAI Chat Model": {
      "ai_languageModel": [[{ "node": "AI Agent", "type": "ai_languageModel", "index": 0 }]]
    },
    "MCP Client": {
      "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
    }
  }
}

导入后：

  1. 打开 OpenAI聊天模型 节点并选择您的OpenAI凭据
  2. 打开 MCP客户端 节点并选择您的MemoryClaw凭据
  3. 保存工作流
  4. 激活工作流（在右上角切换）

6.测试一下！

打开工作流聊天界面并询问：

  • “我在做什么项目？”
  • “谁是我的技术导师？”
  • “我们昨天讨论了什么？”

预期行为：

  • AI代理将使用 memory_search 查询内存文件的工具
  • 结果将从MEMORY.md和MEMORY/*.md文件返回
  • 代理将根据搜索结果回答

故障排除

问题： MCP客户端节点显示“未找到工具：memory_search”

解决方案：

  • 检查一下 run-server.sh 具有指向工作区的正确绝对路径
  • 验证 OPENAI_API_KEY 在MCP凭据中设置
  • 检查n8n日志中的MCP服务器启动错误
  • 直接测试MCP服务器： cd packages/mcp-server && node test-simple.js

问题： 搜索未返回任何结果

解决方案：

  • 确保您的工作区中存在MEMORY.md或MEMORY/*.md文件
  • 检查文件是否包含文本内容
  • 尝试设置 "minScore": 0 在工具参数中查看所有结果
  • 重建项目： pnpm build

问题： “未找到n8n个节点mcp”

解决方案：

  • 必须通过n8n的UI（设置）安装社区节点→ 社区节点）
  • 安装后重新启动n8n
  • 检查n8n版本兼容性（需要n8n 1.0+）

建筑

┌─────────────────────────────────────────────────────────────┐
│  AI Agent (Claude, GPT, etc.) + userId                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  MCP Server (stdio)                                         │
│  Tools: memory_search, memory_get, memory_store, memory_del │
│  + userId param → per-user isolation (Sprint 0 - planned)   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Core Library                                               │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Chunking   │  │   Storage    │  │   Search     │      │
│  │  400 tokens  │  │   SQLite     │  │  BM25 + Vec  │      │
│  │  80 overlap  │  │   + FTS5     │  │   (hybrid)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Memory Files (per user - planned)                          │
│  users/{userId}/MEMORY.md + memory/*.md                     │
│  users/{userId}/memory.db                                   │
└─────────────────────────────────────────────────────────────┘

路线图

第一阶段：记忆搜索✅ 当前

功能 状态 描述
内存存储 ✅ 完成 内存.md+内存/*.md
Markdown分块 ✅ 完成 ~400个令牌，80个重叠
SQLite+FTS5 ✅ 完成 关键字索引
BM25搜索 ✅ 完成 关键字匹配
嵌入缓存 ✅ 完成 基于哈希的重复数据删除
MCP服务器 ✅ 完成 stdio传输，4个工具（搜索、获取、存储、删除）
n8n集成 ✅ 完成 适用于AI Agent节点
集成测试 ✅ 已完成 15个端到端测试
QA场景 ✅ 完成 17个断言，4个真实用户场景

Sprint 0：多用户隔离🎯 下一步

功能 状态 描述
userId参数 🎯 计划 将用户ID添加到所有4个MCP工具
每个用户工作区 🎯 计划中 users/{userId}/MEMORY.md + memory/*.md
每用户数据库 🎯 计划中 users/{userId}/memory.db --完全隔离
经理人才库 🎯 计划 每个用户ID的内存管理器LRU池
向后兼容 🎯 计划 无用户ID→ 默认为 "default" 用户
WhatsApp工作流程 🎯 计划 n8n以电话作为用户ID的示例

第1.5阶段：记忆基础📋 Sprint 0之后

功能 状态 描述
sqlite-vec扩展 📋 计划 负载向量扩展
矢量搜索 📋 计划 余弦相似度搜索
混合合并 📋 计划 70%矢量+30%关键字
嵌入批处理API 📋 计划 OpenAI批次（便宜50%）

阶段2：上下文管理🚧 计划的

功能 状态 描述
令牌计数 📋 计划 测量上下文使用情况
上下文窗口保护 📋 计划 警告/阻止阈值
内存刷新 📋 计划 压实前保存
压实 📋 计划 总结旧对话
上下文修剪 📋 计划 软边+硬边

阶段3：会话生命周期📋 未来

功能 状态 描述
会话管理 📋 计划 重置规则（每日、手动）
会议记录 📋 计划 JSONL存储
会话内存挂钩 📋 计划 自动保存/新建
缓存TTL修剪 📋 计划 人为缓存优化
HTTP适配器 📋 计划 云n8n支持

可用工具

memory_search

使用关键字匹配搜索您的记忆。

{
  "query": "project status",
  "maxResults": 5,
  "minScore": 0,
  "userId": "user_123"
}

注： userId 将在Sprint 0中添加。目前，所有工具都在一个共享工作区上运行。

memory_get

从内存文件中读取特定行。

{
  "path": "memory/projects.md",
  "from": 1,
  "lines": 20,
  "userId": "user_123"
}

memory_store

创建或更新内存文件。

{
  "path": "memory/profile.md",
  "content": "# Profile\nName: Maria\nCompany: TechCorp",
  "userId": "user_123"
}

memory_delete

删除内存文件。

{
  "path": "memory/old-notes.md",
  "userId": "user_123"
}

发展

# Install
pnpm install

# Build
pnpm build

# Test all packages
pnpm test

# Test MCP server only
cd packages/mcp-server
pnpm test:unit        # Unit tests (fast, recommended)
pnpm test:watch       # Watch mode for development

# Build and test MCP Server
pnpm build && pnpm test

看 测试指导 和 建筑 详细说明。

当前限制

限制 原因 计划解决方案
无多用户隔离 无userId参数 Sprint 0:每个用户的工作空间+数据库
仅关键字搜索 未加载sqlite-vec 第1.5阶段：矢量搜索
未压实 尚未实施 第2阶段：压实
仅限本地n8n MCP使用stdio 第3阶段：HTTP适配器
没有令牌指标 尚未实现 第2阶段：令牌计数

贡献

欢迎投稿！我们特别需要以下方面的帮助：

  • Sprint 0：多用户隔离（每个工具、每个用户数据库的用户ID）
  • 第1.5阶段特征：矢量搜索、混合合并
  • 测试：集成测试、多用户隔离测试
  • 文档：使用指南和示例
  • 集成：克劳德桌面、光标、WhatsApp工作流

如何贡献

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

项目结构

memory-claw/
├── packages/
│   ├── core/           # Core library (search, storage, chunking)
│   └── mcp-server/     # MCP Server for AI agents
├── examples/           # Example workspaces
├── docs/               # Documentation
└── test-workspace-mcp/ # Test workspace

许可证

MIT许可证-请参阅 许可证 了解详情。

积分

建筑灵感来自 莫尔特博特，一个开源的人工智能助手。

作者

蒂亚戈·桑托斯 - @tostechbr

给你的人工智能代理记忆的礼物。

相关 MCP