neverinfamous-memory-journal-mcp

Memory Journal MCP 服务

📚 完整文档（Wiki） • 更新日志 • 安全 • 发布文章

🎯 AI 上下文 + 项目智能：借助持久化项目记忆和自动会话交接，串联彼此隔离的 AI 会话，并全面集成 GitHub 工作流。

🚀 快速部署：

• npm 包 - npm install -g memory-journal-mcp
• Docker Hub - 基于 Alpine，提供完整的语义搜索

🧠 不再经历 AI 失忆

在 AI 助手的帮助下管理大型项目时，你会面临一个关键挑战：

• 会话失忆 - 每段新的 AI 对话都从零开始，不了解之前的工作。
• 上下文丢失 - 决策、实现和经验教训散落在彼此隔离的对话中。
• 重复劳动 - AI 提出你已经尝试过或放弃的解决方案。
• 上下文过载 - 每次新对话都要手动复制项目历史。

Memory Journal 通过充当项目的长期记忆，弥合分散的 AI 会话之间的鸿沟。

体验真正具备上下文感知能力的开发：

• “上个月我们为什么为这个服务选择 SQLite 而不是 Postgres？”（语义搜索）
• “对看板上优先级最高的工单运行 /issue-triage 工作流。”（GitHub 操作）
• “最近谁一直在修改 auth 模块？我们的团队协作密度如何？”（团队分析）
• “我卡在这个数据库错误上了。为 @sarah 标记一个 ‘blocker’，让她的 Agent 在下次会话中看到。”（Hush Protocol）
• “关闭问题 #42，并记录一条说明我们如何通过架构修复解决解析错误的记录。”（上下文生命周期）
• “绘制一张可视化图表，展示我最近 10 个架构决策之间的关联。”（知识图谱）

查看完整示例和提示词 →

🎯 我们的独特之处

73 个 MCP 工具 · 19 个工作流提示词 · 46 个资源 · 10 个工具组 · 代码模式 · GitHub 指挥官（问题分类、PR 审查、里程碑冲刺、安全/质量/性能审计） · GitHub 集成（问题、PR、Actions、看板、里程碑、洞察） · 团队协作（共享数据库、向量搜索、跨项目洞察、Hush Protocol 标记）

flowchart TB
    subgraph Session["🤖 AI Session Start"]
        Briefing["📋 Read Briefing<br/>(memory://briefing)"]
    end

    subgraph Core["📝 Journal Operations"]
        Create["Create Entry"]
        Retrieve["Retrieve & Search"]
        Link["Link Entries"]
    end

    subgraph Search["🔍 Hybrid Search"]
        FTS["Keyword (FTS5)"]
        Semantic["Semantic (Vector)"]
        DateRange["Date Range"]
        RRF["Reciprocal Rank Fusion"]
    end

    subgraph GitHub["🐙 GitHub Integration"]
        Issues["Issues & Milestones"]
        PRs["Pull Requests"]
        Actions["GitHub Actions"]
        Kanban["Kanban Boards"]
        Insights["Repository Insights"]
    end

    subgraph Outputs["📊 Outputs"]
        Reports["Standups & Retrospectives"]
        Graphs["Knowledge Graphs"]
        Timeline["Project Timelines"]
    end

    Session --> Core
    Core --> Search
    Core <--> GitHub
    Search --> Outputs
    GitHub --> Outputs

建议规则（添加到 AGENTS.md、GEMINI.md、系统提示词等）

工具筛选

重要

默认情况下，所有快捷方式和工具组都包含 Code Mode（mj_execute_code），以提高令牌使用效率。若要排除它，请在筛选条件中添加 -codemode：--tool-filter starter,-codemode

通过 MEMORY_JOURNAL_MCP_TOOL_FILTER（或 CLI：--tool-filter）控制公开哪些工具：

筛选语法： shortcut、group 或 tool_name（白名单模式）· -group（禁用组）· -tool（禁用工具）· +tool（禁用组后重新启用工具）

自定义选择： 列出各个工具名称以创建自己的白名单：--tool-filter "create_entry,search_entries,semantic_search"

分组： core、search、analytics、relationships、io、admin、github、backup、team、codemode

完整工具筛选指南 →

📋 核心功能

🛠️ 73 个 MCP 工具（10 组）

完整工具参考 →

🎯 19 个工作流提示词

• find-related - 通过语义相似度发现相关条目
• prepare-standup - 每日站会摘要
• prepare-retro - 冲刺回顾
• weekly-digest - 按天整理的每周摘要
• analyze-period - 深入分析特定时期并提供洞察
• goal-tracker - 跟踪里程碑和成就
• get-context-bundle - 包含 Git/GitHub/看板信息的项目上下文
• get-recent-entries - 格式化的近期条目
• project-status-summary - GitHub Project 状态报告
• pr-summary - 拉取请求日志活动摘要
• code-review-prep - 全面的 PR 评审准备
• pr-retrospective - 分析已完成的 PR 并总结经验
• actions-failure-digest - CI/CD 失败分析
• project-milestone-tracker - 跟踪里程碑进度
• confirm-briefing - 向用户确认会话上下文
• session-summary - 创建会话摘要条目，记录已完成事项、待办事项和下次会话上下文
• team-session-summary - 创建回顾式团队会话摘要条目，并安全隔离到团队数据库
• adversarial-plan-review - 多轮对抗式计划评审，包含结构化维度、评分标准和先前计划上下文
• flag-dashboard - 按优先级评估对活跃标记进行分流，并提供解决建议

完整提示词指南 →

📡 46 个资源（29 个静态资源 + 17 个模板）

29 个静态资源（显示在资源列表中）：

• memory://briefing - 会话初始化：为 AI Agent 提供精简上下文（约 350 个 token），包括服务版本、功能范围（工具/资源/提示词）、测试健康状况、尚未发布的变更、分析数据、localTime 和可选的 activeFlags
• memory://instructions - 行为指导：面向 AI Agent 的完整服务说明
• memory://recent - 最近的 10 条条目
• memory://significant - 重要里程碑与突破
• memory://graph/recent - 最近关系的实时 Mermaid 图
• memory://health - 服务健康状况与诊断信息
• memory://graph/actions - CI/CD 叙述图
• memory://actions/recent - 最近的工作流运行记录
• memory://tags - 所有标签及其使用次数
• memory://statistics - 日志统计信息
• memory://rules - 用户规则文件内容，供 Agent 了解
• memory://workflows - 可用 Agent 工作流摘要
• memory://skills - Agent 技能索引（名称、路径、摘录）
• memory://github/status - GitHub 仓库状态概览
• memory://github/insights - 仓库星标数、复刻数和 14 天流量摘要
• memory://github/milestones - 开放的里程碑及其完成百分比
• memory://team/recent - 最近的团队条目及作者信息
• memory://team/statistics - 团队条目数、类型和作者分布
• memory://help - 工具组索引，包含说明和工具数量
• memory://metrics/summary - 自服务启动以来的工具调用聚合指标（调用次数、错误数、token 估算值、持续时间）— HIGH 优先级
• memory://metrics/tokens - 按输出 token 成本排序的各工具 token 使用情况明细 — MEDIUM 优先级
• memory://metrics/system - 进程级指标：内存（MB）、运行时间（s）、Node.js 版本、平台 — MEDIUM 优先级
• memory://metrics/users - 各用户的调用次数（存在 OAuth 用户标识符时填充）— LOW 优先级
• memory://audit - JSONL 运行遥测日志中最近 50 条写入/管理工具调用记录（需要 AUDIT_LOG_PATH）
• memory://flags - 活跃（未解决）团队标记面板（需要 TEAM_DB_PATH）
• memory://flags/vocabulary - 已配置的标记词汇
• memory://flags/history - 最近已解决的标记及解决详情和平均解决时间（最近 7 天）

17 个模板资源（9 个基础模板 + 8 个动态 {repo} 变体）：

• memory://projects/{number}/timeline - 项目活动时间线
• memory://issues/{issue_number}/entries - 与议题关联的条目
• memory://prs/{pr_number}/entries - 与 PR 关联的条目
• memory://prs/{pr_number}/timeline - PR 与日志的组合时间线
• memory://kanban/{project_number} - GitHub Project 看板
• memory://kanban/{project_number}/diagram - 看板 Mermaid 可视化图
• memory://milestones/{number} - 里程碑详情及完成进度
• memory://help/{group} - 按组划分的工具参考，包含参数和注释
• memory://briefing/{repo} - 针对特定仓库的上下文

注意：memory://github/status、memory://github/insights、memory://github/milestones 和 memory://milestones/{number} 资源还支持可选的 /{repo} 路径后缀，用于指定其他仓库。

⚡ 代码模式：最高效率（节省 90% Token）

代码模式（mj_execute_code）是一种革命性方案，最多可大幅减少 90% 的 Token 用量，并默认包含在所有预设中。AI Agent 无需为顺序调用工具消耗数千个 Token，只需进行一次沙盒执行，即可更快地推理。

代码在 worker_threads 沙盒中运行，该沙盒旨在提供安全的多租户进程隔离环境。所有 mj.* API 调用都在沙盒内针对日志执行，并具备以下特性：

• V8 代码生成限制 — 在 V8 引擎级别通过 codeGeneration: { strings: false, wasm: false } 禁用 eval() 和通过字符串构造 Function()
• 冻结原型 — 在 vm 上下文中冻结所有内置原型（Object、Function、Array、Error 等），以防止通过动态构造函数链逃逸
• 静态代码验证 — 通过 18 条正则规则拦截 require()、process、eval()、Reflect.*、Symbol.*、new Proxy() 以及文件系统／网络访问
• 禁用 Proxy 构造函数 — 在沙盒中将 Proxy 设为 undefined，防止滥用元对象协议
• RPC 允许列表 — 主机端验证可防止工作线程调用未经授权的 API 方法
• 速率限制 — 每个客户端每分钟最多执行 60 次
• 硬超时 — 可配置的执行时限（默认 30s）
• 出口边界强制执行 — 限制结果序列化大小，防止超大负载导致 OOM
• 完整 API 访问权限 — 可通过 mj.* 使用全部 10 个工具组（例如 mj.core.createEntry()、mj.search.searchEntries()、mj.github.getGithubIssues()、mj.team.passTeamFlag()）
• 严格的只读契约 — 在 --tool-filter readonly 下调用任何变更方法都会安全地停止沙盒，向 Agent 返回结构化的 { success: false, error: "..." } 响应，而非原始 MCP 协议异常。

⚡ 仅启用代码模式（最大限度节省 Token）

仅启用代码模式运行 — 通过 mj.* API，以单个工具提供相当于全部 69 个工具的能力：

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "args": ["--tool-filter", "codemode"]
    }
  }
}

这只会暴露 mj_execute_code。Agent 使用带类型的 mj.* SDK 编写 JavaScript，在一次执行中组合跨越全部 10 个工具组的操作，并仅返回所需数据。这与 Cloudflare 为其整个 API 开创的 代码模式 相同：无论具备多少种能力，Token 成本都固定不变。

禁用代码模式

如果更倾向于单独调用工具，请排除 codemode：

{
  "args": ["--tool-filter", "starter,-codemode"]
}

🤫 Hush 协议：异步团队协作

Hush 协议通过以结构化、可由机器执行的标记取代嘈杂的 Slack/Teams 消息，为 AI 增强型工作流重新构想团队协作。

遇到阻碍、需要审查或想要广播里程碑时，AI Agent 可以在共享的团队数据库中创建标记：

• 可操作的可见性：活动标记会自动显示在所有团队成员的 memory://briefing 载荷最顶部。当另一位开发者的 Agent 启动会话时，它会立即看到你的阻碍，并能自主协助解决。
• 结构化类型：创建特定类型的标记（blocker、needs_review、help_requested、fyi）。你可以通过 --flag-vocabulary 配置自定义团队词汇。
• 可搜索的历史记录：与消失无踪的聊天消息不同，Hush 标记是永久、可查询的 AI 日志条目。Agent 可以搜索以往的 needs_review 标记，了解架构阻碍是如何克服的。
• 集成站会和回顾信号：活动标记会自动作为上下文信号出现在 prepare-standup 和 prepare-retro 提示词中，因此每日站会和冲刺回顾总能发现尚未解决的阻碍。
• 完整的生命周期管理：通过 team_list_flags 按状态、类型或负责人列出和筛选标记。通过 team_update_flag 更新元数据（提升严重程度、重新分配、添加链接），或重新打开已解决的标记。使用 team_get_flag_analytics 跟踪解决速度、每位用户的工作量和趋势。

仪表板和操作：读取 memory://flags 查看活动仪表板，读取 memory://flags/history 查看近期已解决的标记；使用 /flag-dashboard 提示词，通过严重程度分组和过期检测来引导分类处理；在 Code Mode 中使用 mj.team.passTeamFlag() / mj.team.resolveTeamFlag() / mj.team.teamListFlags() / mj.team.teamUpdateFlag() / mj.team.teamGetFlagAnalytics() 以编程方式管理标记。

Hush 协议完整指南和 Mermaid 时序图 →

🚀 快速开始

选项 1：npm（推荐）

npm install -g memory-journal-mcp

选项 2：从源代码构建

git clone https://github.com/neverinfamous/memory-journal-mcp.git
cd memory-journal-mcp
npm install
npm run build

添加到 MCP 配置

将以下内容添加到 ~/.cursor/mcp.json、Claude Desktop 配置或同类配置中：

基本配置

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/path/to/your/git/repo\",\"project_number\":1}}",
        "ALLOWED_IO_ROOTS": "/path/to/your/git/repo"
      }
    }
  }
}

高级配置（推荐）

展示服务的全部功能，包括多项目路由、团队协作、Copilot 感知和上下文注入。

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "DB_PATH": "/path/to/your/memory_journal.db",
        "TEAM_DB_PATH": "/path/to/shared/team.db",
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/path/to/repo\",\"project_number\":1},\"other-repo\":{\"path\":\"/path/to/other\",\"project_number\":5}}",
        "ALLOWED_IO_ROOTS": "/path/to/repo,/path/to/other,/path/to/your/skills",
        "AUTO_REBUILD_INDEX": "true",
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "codemode",
        "CODEMODE_INTERNAL_FULL_ACCESS": "true",
        "BRIEFING_ENTRY_COUNT": "3",
        "BRIEFING_SUMMARY_COUNT": "1",
        "BRIEFING_INCLUDE_TEAM": "true",
        "BRIEFING_ISSUE_COUNT": "3",
        "BRIEFING_PR_COUNT": "3",
        "BRIEFING_PR_STATUS": "true",
        "BRIEFING_WORKFLOW_COUNT": "3",
        "BRIEFING_WORKFLOW_STATUS": "true",
        "BRIEFING_COPILOT_REVIEWS": "true",
        "RULES_FILE_PATH": "/path/to/your/RULES.md",
        "SKILLS_DIR_PATH": "/path/to/your/skills",
        "MEMORY_JOURNAL_WORKFLOW_SUMMARY": "/deploy: prod deployment | /audit: security scan",
        "AUDIT_LOG_PATH": "/path/to/your/mcp-audit.jsonl",
        "TEAM_AUTHOR": "your_username"
      }
    }
  }
}

💡 提示： 优化你的上下文窗口！日志条目（BRIEFING_ENTRY_COUNT）记录频繁、细粒度的操作（例如修复错误、实施步骤）。会话摘要（BRIEFING_SUMMARY_COUNT）呈现高层次回顾，旨在跨不同 AI 会话持续传递战略上下文。合理使用两者，让 Agent 简报高度聚焦！

📋 自定义会话简报

memory://briefing 资源会在每次会话开始时动态组装，提供丰富且节省令牌的环境上下文。默认情况下，它会自动呈现：

• 系统状态： 服务版本、功能状态、资源/工具数量、测试健康状况，以及 memory://metrics/summary 线索。
• 代码库上下文： Git 工作树状态、尚未发布的更改、精确的代码映射路径，以及按优先级排序的守门 CI 工作流。
• 环境上下文： 活动工作区路径、本地时间、分析数据和活动的 Hush 协议标记。

你可以从三个维度精确控制 Agent 还会看到哪些内容：

上下文注入： 设置 RULES_FILE_PATH 和 SKILLS_DIR_PATH，即可将用户规则和 Agent 技能作为配套资源（memory://rules、memory://skills）与简报一同呈现。

仓库指定： 在多仓库设置中，Agent 可读取 memory://briefing/{repo}，获取针对 PROJECT_REGISTRY 中注册的特定仓库的简报。

"BRIEFING_ENTRY_COUNT": "1",
"BRIEFING_SUMMARY_COUNT": "0",
"INSTRUCTION_LEVEL": "essential"

"BRIEFING_ENTRY_COUNT": "5",
"BRIEFING_SUMMARY_COUNT": "3",
"BRIEFING_INCLUDE_TEAM": "true",
"BRIEFING_ISSUE_COUNT": "5",
"BRIEFING_PR_COUNT": "3",
"BRIEFING_PR_STATUS": "true",
"BRIEFING_COPILOT_REVIEWS": "true",
"INSTRUCTION_LEVEL": "full"

"BRIEFING_WORKFLOW_COUNT": "5",
"BRIEFING_WORKFLOW_STATUS": "true",
"BRIEFING_ISSUE_COUNT": "3",
"BRIEFING_PR_COUNT": "3",
"BRIEFING_PR_STATUS": "true",
"BRIEFING_COPILOT_REVIEWS": "true"

完整的简报自定义指南 →

变体（修改上述配置）：

重启 MCP 客户端，然后开始记录日志！

选项 3：HTTP/SSE 传输（远程访问）

🔒 安全态势：Stdio 与 HTTP

• Stdio（默认）： 在本地 IDE 或命令行环境的安全边界内隐式运行。由于执行环境已受信任，因此无需显式身份验证。
• HTTP/SSE： 通过网络套接字公开服务。默认情况下，HTTP 仅绑定到 localhost，并阻止通配符 CORS，以防止未经授权的访问和 CSRF 攻击。公开绑定到网络（--server-host 0.0.0.0）需要显式身份验证（--auth-token 或 --oauth-enabled）。如果尝试在未采取安全措施的情况下将服务公开到网络，服务将抛出致命错误。

如需远程访问或使用基于 Web 的客户端，请以 HTTP 模式运行服务：

memory-journal-mcp --transport http --port 3000

如需绑定到所有接口（容器必需）并启用自动主动分析调度器（例如，每日摘要），必须提供身份验证令牌：

export MCP_AUTH_TOKEN="your_secure_random_token"
memory-journal-mcp --transport http --port 3000 --server-host 0.0.0.0 --digest-interval 1440

端点：

会话管理： 服务默认使用有状态会话。后续请求中需包含 mcp-session-id 标头（在初始化时返回）。

• OAuth 2.1 — RFC 9728/8414、JWT/JWKS、细粒度作用域（通过 --oauth-enabled 选择启用）
• 7 个安全标头 — CSP、HSTS（选择启用）、X-Frame-Options 等
• 速率限制 — 每个 IP 每分钟 100 个请求 · CORS — 可配置的多源（精确匹配）· 1MB 请求体限制
• 服务超时 — 请求（120s）、保持活动（65s）、标头（66s）· 404 处理程序 · 跨协议防护
• 构建溯源 · SBOM · 供应链证明 · 以非 root 用户身份运行

curl 示例：

初始化会话（返回 mcp-session-id 标头）：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

列出工具（使用会话）：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

无状态模式（无服务器）

对于无服务器部署（Lambda、Workers、Vercel），请使用无状态模式：

memory-journal-mcp --transport http --port 3000 --stateless

自动调度（仅限 HTTP）

在 HTTP/SSE 模式下，使用 CLI 标志启用定期维护任务。这些任务通过 setInterval 在进程内运行，无需外部 cron。

注意： stdio 传输会忽略这些标志，因为 stdio 会话生命周期较短（与 IDE 会话绑定）。对于 stdio，请使用操作系统级调度（Task Scheduler、cron），或手动运行备份/清理工具。

memory-journal-mcp --transport http --port 3000 \
  --backup-interval 60 --keep-backups 10 \
  --vacuum-interval 1440 \
  --rebuild-index-interval 720

每个任务都隔离错误——某个任务失败不会影响其他任务。可通过 memory://health 查看调度器状态（上次运行时间、结果、下次运行时间）。

GitHub 集成配置

当配置了 PROJECT_REGISTRY，或 MCP 服务在 Git 仓库内运行时，GitHub 工具（get_github_issues、get_github_prs 等）会根据你的 Git 上下文自动检测仓库。

动态上下文解析与自动检测

执行 GitHub 工具（issues、PR、上下文等）时，服务会按以下顺序解析仓库上下文：

1. 动态项目路由：如果 Agent 传入的 repo 字符串与 PROJECT_REGISTRY 中的某个键匹配，服务会动态挂载映射到该项目的物理目录。在本地执行 git 命令，并自动推断 owner。
2. 显式覆盖：如果 Agent 显式提供了 owner 和 repo，这些值会覆盖 API 调用的自动检测结果。
3. 缺少上下文：如果没有 PROJECT_REGISTRY 或显式参数，服务会阻止执行并返回 {requiresUserInput: true}，以提示 Agent。

自动项目路由（看板 / issues）

创建 issue 或查看 / 移动看板卡片时，服务需要 GitHub Project 编号。确定方式如下：

1. 检查 Agent 传入的原始 project_number 参数。
2. 检查 repo 字符串是否与 PROJECT_REGISTRY 中的条目完全匹配，并将其无缝映射到预先配置的 project_number。
3. 如果已设置，则回退到全局定义的 DEFAULT_PROJECT_NUMBER。

🔐 OAuth 2.1 身份验证

对于生产部署，请在 HTTP 传输上启用 OAuth 2.1 身份验证：

支持的权限范围：

快速开始：

memory-journal-mcp --transport http --port 3000 \
  --oauth-enabled \
  --oauth-issuer https://auth.example.com/realms/mcp \
  --oauth-audience memory-journal-mcp \
  --oauth-jwks-uri https://auth.example.com/realms/mcp/protocol/openid-connect/certs

也可以通过环境变量配置：

export OAUTH_ENABLED=true
export OAUTH_ISSUER=https://auth.example.com/realms/mcp
export OAUTH_AUDIENCE=memory-journal-mcp
export OAUTH_CLOCK_TOLERANCE=5
memory-journal-mcp --transport http --port 3000

**注意：**OAuth 为可选功能。未启用时，服务会回退到通过 MCP_AUTH_TOKEN 环境变量进行简单令牌身份验证，或在不进行身份验证的情况下运行。

🔄 会话管理

1. 会话开始 → Agent 读取 memory://briefing（或 memory://briefing/{repo}）并显示项目上下文
2. 会话摘要 → 使用 /session-summary 记录进度和下一会话的上下文
3. 下一会话的简报会包含上一会话的摘要——上下文无缝衔接

🔧 配置

GitHub 集成（可选）

export GITHUB_TOKEN="your_token"              # For Projects/Issues/PRs

权限范围：repo、project、read:org（仅用于组织级项目发现）

GitHub 管理功能

Memory Journal 采用 混合式 GitHub 管理方案：

MCP Server 工具（读取 + 看板 + 里程碑 + 议题生命周期）：

• get_github_issues / get_github_issue - 查询议题
• get_github_prs / get_github_pr - 查询拉取请求
• get_github_context - 完整的代码库上下文
• get_kanban_board / add_kanban_item / move_kanban_item / delete_kanban_item - 看板管理
• get_github_milestones / get_github_milestone - 跟踪里程碑进度及完成百分比
• create_github_milestone / update_github_milestone / delete_github_milestone - 里程碑 CRUD
• get_repo_insights - 代码库流量与分析（星标、克隆、浏览量、引荐来源、热门路径）
• create_github_issue_with_entry / close_github_issue_with_entry - 带日志关联的议题生命周期管理

为什么采用这种设计？ MCP 服务专注于将日志条目与 GitHub 集成的增值功能（看板视图、里程碑、时间线资源、上下文关联）。标准的 GitHub 变更操作（创建／关闭议题、合并 PR、管理发布）由 Agent 通过 gh CLI 直接处理。

查看完整的 GitHub 集成指南 →

GitHub Commander 工作流

服务器原生内置 github-commander Agent 技能（可通过 memory://skills/github-commander 访问）。它为 AI 助手扩展了 9 种自主 DevOps 工作流，用于代码库维护：议题分类、里程碑冲刺、PR 审查、Copilot 审计、安全审计、代码质量审计、性能审计、路线图启动和依赖项更新。配置 PROJECT_* 环境覆盖项，即可在 Agent 任务期间强制执行与 CI 匹配的本地验证层！

🏗️ 架构

数据流

flowchart TB
    AI["🤖 AI Agent<br/>(Cursor, Windsurf, Claude)"]

    subgraph MCP["Memory Journal MCP Server"]
        Tools["🛠️ 73 Tools"]
        Resources["📡 46 Resources"]
        Prompts["💬 19 Prompts"]
    end

    subgraph Storage["Persistence Layer"]
        SQLite[("💾 SQLite<br/>Entries, Tags, Relationships")]
        Vector[("🔍 Vector Index<br/>Semantic Embeddings")]
        Backups["📦 Backups"]
    end

    subgraph External["External Integrations"]
        GitHub["🐙 GitHub API<br/>Issues, PRs, Actions"]
        Kanban["📋 Projects v2<br/>Kanban Boards"]
    end

    AI <-->|"MCP Protocol"| MCP
    Tools --> Storage
    Tools --> External
    Resources --> Storage
    Resources --> External

技术栈

┌─────────────────────────────────────────────────────────────┐
│ MCP Server Layer (TypeScript)                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ Tools (73)      │  │ Resources (47)  │  │ Prompts (19)│  │
│  │ with Annotations│  │ with Annotations│  │             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ Native SQLite Engine                                        │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ better-sqlite3  │  │ sqlite-vec      │  │ transformers│  │
│  │ (High-Perf I/O) │  │ (Vector Index)  │  │ (Embeddings)│  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ SQLite Database with Hybrid Search                          │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ entries + tags + relationships + embeddings + backups   ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

🔧 技术亮点

性能与可移植性

• TypeScript + 原生 SQLite - 采用同步 I/O 的高性能 better-sqlite3
• sqlite-vec - 通过 SQLite 扩展进行向量相似度搜索
• @huggingface/transformers - 在 JavaScript 中运行本地 ML 嵌入模型
• 后台预热 - 服务器启动时会异步将模型权重（约 23MB）加载到内存，以避免首次请求延迟。如果服务器在预热完成前被调用，首次语义搜索或向量插入会遇到受网络影响的冷启动（约 1.5s - 3s），此时权重会缓存在本地。

性能基准测试

Memory Journal 专为 AI 任务执行期间的极低开销而设计。我们包含一个 vitest bench 测试套件，以维持这些基准保证：

• 数据库读取：操作耗时不到一毫秒。calculateImportance 的速度约为检索 50 条最新条目的 13-14 倍。
• 向量搜索引擎：借助 sqlite-vec 和 SQL 原生 KNN 查询，搜索（约 140-220 ops/sec）和索引（约 1600-1900+ ops/sec）均具有高吞吐量。
• 核心 MCP 例程：getTools 使用缓存的 O(1) 分派，速度约为 get_recent_entries 的 4800-7000 倍。create_entry 和 search_entries 通过完整的 MCP 层执行，额外开销不到一毫秒。

要在本地运行基准测试套件：

npm run bench

测试

通过两个测试框架进行了全面测试：

npm test          # Unit + integration tests
npm run test:e2e  # End-to-end HTTP/SSE transport tests

安全性

• 确定性错误处理 - 每个工具都会返回结构化的 {success, error, code, category, suggestion, recoverable} 响应，并提供可操作的上下文；不会抛出原始异常、静默失败或显示误导性消息
• 本地优先 - 所有数据均存储在本地，不会调用外部 API（可选的 GitHub 除外）
• 输入验证 - Zod 模式、内容大小限制、防止 SQL 注入
• 路径遍历防护 - 验证备份文件名
• MCP 2025-03-26 注解 - 行为提示（readOnlyHint、destructiveHint 等）
• HTTP 传输强化 - 7 个安全标头、可配置的多源 CORS、1MB 请求体限制、内置速率限制（100 次请求/分钟）、服务器超时、HSTS（可选启用）、30 分钟会话超时、404 处理程序、跨协议防护
• 令牌清理 - 自动从错误日志中隐藏 GitHub 令牌和凭据

数据与隐私

• 单个 SQLite 文件 - 数据由你掌控
• 可移植 - 可将 .db 文件移至任何位置
• 软删除 - 可恢复条目
• 恢复时自动备份 - 避免意外丢失数据

📚 文档与资源

• GitHub Wiki - 完整文档
• Copilot 设置指南 - IDE Agent 与 GitHub Copilot 之间的跨 Agent 记忆桥接
• 部署指南 - CI/CD 流水线、环境和版本升级检查清单
• Docker Hub - 容器映像
• npm 包 - Node.js 发行版
• 问题反馈 - 错误报告和功能请求

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🤝 贡献

由开发者打造，服务开发者。欢迎提交 PR！请参阅 CONTRIBUTING.md 了解指南。