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. 填写以下字段：

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                                   │
└─────────────────────────────────────────────────────────────┘

路线图

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

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

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

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

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

可用工具

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

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

当前限制

贡献

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

• 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

______________________________________________________________________

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