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。