Janus — 为 AI 编程助手打造的外部认知操作系统

https://github.com/njaulj/yimemory.git

一句话

Janus 是一个零依赖的 MCP 服务器，给 AI 助手装上"前额叶"——既记（长期记忆）又管（主动约束）。

每一次新对话 Claude 都是一张白纸。Janus 记住你上次做到哪了、不要改什么、为什么这么做。

五分钟理解 Janus

┌──────────────────────────────────────────────┐
│  核心三问（每问一个工具）                       │
│                                              │
│  "上次这个项目做到哪了？"      → janus_recall   │
│  "这个决定很重要，记住它"      → janus_remember │
│  "这个文件不能改，我上次踩过坑"  → janus_guard   │
│                                              │
│  其余 12 个工具都是这三问的增强。                │
└──────────────────────────────────────────────┘

典型工作流

新项目：
  janus_init → bootstrap 自动从 git log + package.json 提炼初始知识
  → janus_remember × 3 （存关键决策）
  → janus_guard （每次文件修改前检查）

第二天继续：
  janus_init → 自动恢复 20+ 节点、决策、约束
  → janus_recall("定价引擎") → 返回准确的 pricing_engine.go
  → 开始工作，不需要从头解释项目

跨设备（ Mac → iPad ）：
  git push （.janus/ 随代码同步）
  → 另一台机器 git pull → janus_init → 自动加载所有记忆

核心能力

安装与部署

Janus 是一个 MCP over stdio 服务器。配置一次，所有支持 MCP 的 AI 编程工具（ Claude Code 、Cursor 、Codex 、Cline 等）都能自动发现并使用它。

极简版（ Claude Code ，30 秒）

cd /path/to/janus
# 编辑 ~/.claude/settings.json ，加入:
# {
#   "mcpServers": {
#     "janus": {
#       "type": "stdio",
#       "command": "node",
#       "args": ["/absolute/path/to/janus/src/index.js"]
#     }
#   }
# }

# 或者用 Claude Code 的 CLI 直接加:
claude mcp add janus -- node /absolute/path/to/janus/src/index.js

重启 Claude Code ，Janus 即自动可用。在对话中输入 janus_init 开始。

详细教程：Claude Code

Step 1：确认 Janus 能启动

cd /path/to/janus
node src/index.js
# 如果输出 "[janus] ST-DKG + PCSS MCP Server v0.3.0 starting (stdio)" 就 OK
# 按 Ctrl+C 退出

Step 2：配置 MCP 服务器

编辑 ~/.claude/settings.json（没有就新建）：

{
  "mcpServers": {
    "janus": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/you/projects/janus/src/index.js"],
      "env": {
        "JANUS_HOME": "/Users/you/.janus"
      }
    }
  }
}

• command：你的 Node.js 路径（which node 查看）
• args[0]：src/index.js 的绝对路径
• env.JANUS_HOME（可选）：指定 Janus 数据存储目录，默认 ~/.janus/

Step 3：重启 Claude Code

关掉重开。在新对话中，你应该能看到 Janus 的 16 个工具出现在工具列表里。

Step 4：初始化

在 Claude Code 对话中：

janus_init(projectName="my-project", projectPath="/path/to/my-project")

如果项目已有大量文件，Janus 会自动引导（ bootstrap ）——从 git log + package.json + README 提炼初始记忆。

Step 5：安装 Git Hook （可选，推荐）

# 在 Claude Code 对话中执行：
janus_absorb(action="install-hook", projectPath="/path/to/my-project")

之后每次 git commit，Janus 自动从 diff 中提取知识，实现"伴随式学习"。

其他 MCP 兼容工具

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "janus": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/janus/src/index.js"]
    }
  }
}

VS Code + Cody / Codex / Continue

编辑 ~/.vscode/mcp.json 或项目根目录的 .mcp.json：

{
  "mcpServers": {
    "janus": {
      "type": "stdio",
      "command": "node",
      "args": ["src/index.js"],
      "env": {}
    }
  }
}

如果放在项目根目录，用相对路径即可（src/index.js）。

Windsurf / Zed / Cline

以上任一工具都支持 MCP stdio 协议。配置格式相同——找到其 MCP 配置文件，加入 janus 的 entry 。

常见问题

Q: 提示 "No project loaded. Run janus_init first"? 每次新对话都要 janus_init，这是 Janus 知道"现在在哪个项目工作"的方式。已 init 过的项目会自动恢复状态。

Q: 如何在多台设备间同步？

janus_init(projectName="my-project", projectPath=".", storage="local")
# 这会把 .janus/ 放在项目根目录
git add .janus/ && git commit -m "janus sync" && git push
# 另一台设备 git pull 后 janus_init 即可恢复所有记忆

Q: 数据存在哪？

• global 模式（默认）：~/.janus/projects/{id}/
• local 模式：{项目根目录}/.janus/projects/{id}/

Q: 占用多少磁盘空间？ 一个活跃使用 3 个月的项目，graph.json 大约 50-200KB 。Timeline 按天追加，JSONL 格式，每分钟约 2KB 。

Q: 可以用 npx 或全局安装吗？ 可以。Janus 是零依赖的——npx 或用 Bun/Deno 替代 Node.js 均可，不加任何依赖包。

快速开始

# 进入项目，启动 Janus （ Claude Code 会自动通过 MCP 连接）
cd your-project
janus_init(projectName="my-project", projectPath=".")

# 如果你想跨设备同步（推荐）
janus_init(projectName="my-project", projectPath=".", storage="local")
# 之后: git add .janus/ && git commit -m "janus sync" && git push

# 探索代码库
janus_phase(phase="discover", goal="理解项目架构")
janus_recall(query="这个项目的技术栈")

# 开始工作
janus_phase(phase="execute", goal="修复登录页面的样式", files=["src/**"])
# 每次文件修改前: janus_guard(...)

# 记录关键决策
janus_remember(type="decision", label="选择 Redis 而不是 Memcached", content="因为...")

# 设定约束
janus_constraint(description="永远不要修改 auth middleware 的签名", scope="file", filePattern="src/middleware/auth.go")

Token 经济学

Janus 是知识的复利模型，不是即时的省钱工具。

Session 1:  Janus 多花 6.5K tokens （ bootstrap + remember × 3 + guard × 10 ）
Session 2:  基本扯平（ recall 省 2K ，guard 多花 1.5K ）
Session 3+: 开始省钱（每次 0.5-2K 节省，随着图变稠密越省越多）

一次性任务用 Janus 是亏的。持续迭代同一项目才值。

设计哲学

• 领域无关：软件项目、小说、画稿、论文、音乐 — 节点类型可扩展，不预设领域
• 零依赖：纯 Node.js 标准库，不需要 embedding API 、vector DB 、LLM 、任何第三方服务
• 本地离线：代码从不离开设备，适合隐私敏感场景
• Git 即同步层：不需要服务器、账号系统、同步协议
• 三个核心工具 > 十五个工具：remember + recall + guard 是第一公民，其余是增强

与竞品的区别

Janus 不是"给 LLM 装个笔记本"（数据库），而是"给 AI 助手装个前额叶"（既记又管）。

项目统计

• 3,000+ 行 JavaScript （零依赖）
• 88 个单元测试，14 个测试套件
• 16 个 MCP 工具（ 3 核心 + 13 增强，含 janus_absorb / janus_timeline / janus_sync ）
• 6 种节点类型 + 5 种边类型 + 4 种衰减曲线
• 2 个存储模式（ global ~/.janus/ + local .janus/）

研发历史

完整的技术文档在 JANUS.md。