{"id":51486744,"url":"https://github.com/junknet/agent-mem","last_synced_at":"2026-07-07T07:02:06.092Z","repository":{"id":334399456,"uuid":"1141232992","full_name":"junknet/agent-mem","owner":"junknet","description":"High-performance, pure Go memory middleware for AI Agents (Claude/Cursor). Features active file watching, auto-distillation via LLM, and 'Single Source of Truth' versioning. Native MCP support.","archived":false,"fork":false,"pushed_at":"2026-03-15T07:35:42.000Z","size":199,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T15:58:56.400Z","etag":null,"topics":["agentic-workflows","ai-memory","claude","cursor","developer-tools","embeddings","file-watcher","generative-ai","go","golang","knowledge-management","llm","mcp","mcp-server","model-context-protocol","pgvector","postgresql","rag","semantic-search","vector-database"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/junknet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T13:54:06.000Z","updated_at":"2026-03-15T07:35:45.000Z","dependencies_parsed_at":"2026-01-25T02:01:24.241Z","dependency_job_id":null,"html_url":"https://github.com/junknet/agent-mem","commit_stats":null,"previous_names":["junknet/agent-mem"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/junknet/agent-mem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junknet%2Fagent-mem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junknet%2Fagent-mem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junknet%2Fagent-mem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junknet%2Fagent-mem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junknet","download_url":"https://codeload.github.com/junknet/agent-mem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junknet%2Fagent-mem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35218117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai-memory","claude","cursor","developer-tools","embeddings","file-watcher","generative-ai","go","golang","knowledge-management","llm","mcp","mcp-server","model-context-protocol","pgvector","postgresql","rag","semantic-search","vector-database"],"created_at":"2026-07-07T07:02:05.278Z","updated_at":"2026-07-07T07:02:06.043Z","avatar_url":"https://github.com/junknet.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Memory (Project Cortex)\n\n\u003e **赋予 AI Agent 长期记忆与自我进化能力**\n\u003e\n\u003e 一个基于 **Go** 实现的轻量级、高性能知识库中间件。支持 LLM 触发入库、智能语义更新与 MCP 协议。\n\n---\n\n## 核心特性\n\n*   **极速架构**: 纯 Go 实现，单二进制文件，资源占用极低\n*   **LLM 触发入库**: 由端上 LLM/客户端在合适时机调用 `mem.ingest_memory`\n*   **认知智能**:\n    *   **查询扩展**: 自动扩展搜索关键词提升召回率\n    *   **LLM 仲裁**: 两层冲突检测（向量筛选 + LLM 判断），智能决策 REPLACE/KEEP_BOTH/SKIP\n    *   **单一真相**: 同主题新知识自动替换旧知识\n*   **标准接口**: 原生支持 **Model Context Protocol (MCP)**，无缝对接 Claude Desktop, Cursor, Gemini CLI\n*   **极客哲学**: 硬删除模式，旧知识直接物理抹除，拒绝数据膨胀\n\n## 架构概览\n\n```mermaid\ngraph LR\n    User[\"LLM / Client\"] --\u003e Ingester[\"Ingest Pipeline\"]\n\n    subgraph CoreLogic [\"Core Logic\"]\n        Ingester --\u003e Summarize[\"Summarize\"]\n        Summarize --\u003e Tag[\"Extract Tags\"]\n        Tag --\u003e Chunk[\"Chunk\"]\n        Chunk --\u003e Embed[\"Vectorize\"]\n        Embed --\u003e Arbiter[\"LLM Arbitrate\"]\n    end\n\n    Arbiter --\u003e DB[(\"PostgreSQL + pgvector\")]\n\n    User[\"Claude / Cursor\"] -- MCP Protocol --\u003e Server[\"MCP Server\"]\n    Server --\u003e DB\n```\n\n## 快速开始\n\n### 1. 依赖准备\n\n确保已安装 [Docker](https://www.docker.com/) 和 [Go 1.25+](https://go.dev/)。\n\n```bash\n# 启动 PostgreSQL (带 pgvector 扩展)\ndocker-compose up -d\n```\n\n### 2. 配置环境\n\n```bash\ncp .env.example .env\nvim .env\n```\n\n```env\nDASHSCOPE_API_KEY=sk-xxxxxxxxxxxx\nDATABASE_URL=postgresql://cortex:cortex_password_secure@localhost:5440/cortex_knowledge\nAGENT_MEM_HTTP_TOKEN=your-strong-token\nAGENT_MEM_OWNER_ID=personal\n```\n\n### 3. 编译与运行\n\n```bash\n# 编译\ncd mcp-go \u0026\u0026 go build -o ../agent-mem ./cmd/agent-mem-mcp \u0026\u0026 cd ..\n\n# HTTP 模式\n./agent-mem --transport http --host 127.0.0.1 --port 8787\n\n# STDIO 模式（MCP 客户端）\n./agent-mem --transport stdio\n\n# 重置数据库（首次或升级时）\n./agent-mem --reset-db --reset-only\n```\n\n## PATH 工具（开箱即用）\n\n一键安装到 PATH（默认 `/usr/local/bin`）：\n\n```bash\n./bin/agent-mem-install\n```\n\n安装后可直接使用：\n\n```bash\nagent-mem              # 启动 MCP 服务（前台）\nagent-mem-reset-db     # 清空并重建数据库\nagent-mem-status       # 查看端口状态\nagent-mem-stop         # 停止服务\n```\n\n## 内容类型（严格互斥）\n\n| 类型 | 英文 | 定义 | 写入时机 |\n|:---:|:---:|:---|:---|\n| 需求功能 | `requirement` | PRD、功能描述、业务规则 | 讨论/确认需求后 |\n| 计划任务 | `plan` | 任务清单、TODO、里程碑 | 制定开发计划后 |\n| 开发 | `development` | 架构设计、API定义、技术方案 | 设计/实现确定后 |\n| 测试验收 | `testing` | 测试计划、用例、验收报告 | 测试/验收完成后 |\n| 经验沉淀 | `insight` | 踩坑记录、最佳实践、注意事项 | 遇到问题并解决后 |\n\n## MCP 工具\n\n| 工具 | 说明 | 返回状态 |\n|:---|:---|:---|\n| `mem.ingest_memory` | 写入记忆 | `created`(新ID) / `updated`(旧ID) / `skipped`(已存在ID) |\n| `mem.search` | 语义检索 | 片段列表 |\n| `mem.get` | 获取全文 | 完整内容 |\n| `mem.timeline` | 时间线查询 | 按时间排序 |\n| `mem.list_projects` | 项目列表 | 项目摘要 |\n\n## HTTP 接口\n\n- `POST /ingest/memory` - 写入记忆\n- `GET /memories/search` - 语义检索\n- `GET /memories` - 获取全文\n- `GET /memories/timeline` - 时间线\n- `GET /projects` - 项目列表\n- `/sse` - SSE 传输（MCP）\n- `/mcp` - Streamable HTTP（MCP）\n\n## 冲突检测机制\n\n```\n新内容入库\n    │\n    ▼\n┌──────────────────┐\n│ 向量相似度筛选   │ ── 找出语义相似的已有知识\n└────────┬─────────┘\n         │ similarity \u003e 0.85\n         ▼\n┌──────────────────┐\n│  LLM 智能仲裁    │ ── 比较新旧摘要，判断关系\n└────────┬─────────┘\n         │\n    ┌────┼────┬────┐\n    ▼    ▼    ▼    ▼\n REPLACE  KEEP   SKIP\n (替换)  _BOTH  (跳过)\n        (保留)\n```\n\n- **REPLACE**: 同主题更新，替换旧知识\n- **KEEP_BOTH**: 不同主题，保留两者\n- **SKIP**: 完全重复，跳过写入\n\n## 升级与迁移\n\n### 从旧版本升级\n\n系统启动时会自动执行迁移脚本：\n- 自动添加 `avg_embedding` 字段\n- 自动添加 `summary`、`tags` 字段（如缺失）\n- 已有索引不受影响\n\n**注意**：旧数据（无 `avg_embedding`）不会参与冲突检测，建议：\n1. 使用 `--reset-db --reset-only` 重建数据库（推荐，数据量小时）\n2. 或手动 backfill 旧数据的向量\n\n### 首次部署\n\n```bash\n./agent-mem --reset-db --reset-only\n```\n\n## 客户端接入\n\n### Claude Desktop / Code\n\n编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-mem\": {\n      \"command\": \"/absolute/path/to/agent-mem\",\n      \"args\": [\"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n### 访问令牌（可选）\n\n如果设置了 `AGENT_MEM_HTTP_TOKEN`，HTTP/SSE/MCP 请求必须携带令牌：\n- Header：`Authorization: Bearer \u003ctoken\u003e`\n- 或 Header：`X-Agent-Mem-Token: \u003ctoken\u003e`\n- 或 URL：`/sse?token=\u003ctoken\u003e`、`/mcp?token=\u003ctoken\u003e`、`/memories/search?token=\u003ctoken\u003e`\n\n### Codex CLI（`~/.codex/config.toml`）\n\n```toml\n[mcp_servers.agent-mem]\nurl = \"http://127.0.0.1:8787/sse\"\n```\n\n### Gemini CLI（`~/.gemini/config.yaml`）\n\n```yaml\nmcpServers:\n  agent-mem:\n    url: http://127.0.0.1:8787/sse\n```\n\n如启用 token，把 `url` 改为：`http://127.0.0.1:8787/sse?token=\u003ctoken\u003e`。\n\n### Cursor (Beta)\n\n- **Type**: SSE\n- **URL**: `http://127.0.0.1:8787/sse`\n\n## 全局提示词\n\n详见 `docs/LLM_PROMPTS.md`，包含：\n- 完整的提示词模板\n- 5 个最佳实践示例\n- 类型选择决策树\n\n## 配置说明\n\n`config/settings.yaml`:\n\n```yaml\nversioning:\n  semantic_similarity_threshold: 0.85  # 触发仲裁的相似度阈值\n\nembedding:\n  provider: qwen\n  model: text-embedding-v4\n  dimension: 1536\n\nchunking:\n  chunk_size: 500\n  overlap: 50\n```\n\n## 开发指南\n\n```bash\n# 运行单元测试\ncd mcp-go/cmd/agent-mem-mcp \u0026\u0026 go test -v\n\n# 运行 E2E 测试\npython scripts/e2e_test_go.py\n\n# 集成测试（需要数据库和 API Key）\nAGENT_MEM_INTEGRATION=1 go test -v\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunknet%2Fagent-mem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunknet%2Fagent-mem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunknet%2Fagent-mem/lists"}