elefante

Elefante

面向 MCP Agent 的开放式、Git 原生记忆协议：可移植、可检查、有版本记录，且可由人编辑。

Your agent's memory is a Git repo you own.
Every memory is a Markdown file you can read.
Every change is a commit you can audit.
Any MCP agent can connect to it.

---

为什么

每个 AI Agent 都有自己的记忆系统。Claude 的记忆只能与 Claude 配合使用。ChatGPT 的记忆只能与 ChatGPT 配合使用。它们全都不透明、受供应商锁定，且不可移植。

Elefante 采用了不同的方法。它不以优化检索质量为目标，而是专注于所有权、可审计性和可移植性——当记忆是一项一等资产，而非隐藏的实现细节时，这些才是真正重要的方面。

问题	答案
谁拥有我的 Agent 记忆？	你。它是一个 Git 仓库。
我的 Agent 对我了解什么？	cat memories/user/*.md
自上周以来有什么变化？	git log --since="1 week ago"
如何在 Claude、Codex 和 Cursor 之间使用？	让它们连接到同一个 MCP 服务。
如何备份？	每个克隆都是完整备份。
如何撤销错误的记忆？	git revert

快速开始

# Install
npm install -g elefante-mcp

# Initialize vault (uses a private GitHub repo as storage)
elefante init [email protected]:yourname/my-memory.git

# Add your first memory
elefante add \
  --name "TypeScript strict mode" \
  --type user \
  --body "Always enable strict: true in tsconfig.json"

# Search
elefante search "typescript"

# Check status
elefante status

连接到你的 Agent

从终端操作（启动 Claude Code 之前）：

claude mcp add --scope user elefante -- npx -y elefante-mcp mcp

在 Claude Code 内操作（会话期间）：

/mcp add --scope user elefante -- npx -y elefante-mcp mcp

或手动操作——添加到你的 MCP 配置中（~/.claude.json、.cursor/mcp.json 等）：

{
  "mcpServers": {
    "elefante": {
      "command": "npx",
      "args": ["-y", "elefante-mcp", "mcp"]
    }
  }
}

Cursor / VS Code / Codex——使用相同的配置。任何支持 MCP 的 Agent 都可以读写同一个保险库。

连接后，你的 Agent 会获得 7 个工具：memory_write、memory_read、memory_search、memory_list、memory_update、memory_delete、memory_sync。

自动发现

Elefante 会在启动时通过 MCP instructions 将最重要的记忆直接注入 Agent 的系统提示词。Agent 无需先搜索，就能看到你的偏好、反馈和项目上下文。

不需要 CLAUDE.md 技巧。不需要“搜索我的 Elefante 记忆”提示词。它开箱即用。

项目感知记忆

Elefante 会自动检测你当前所在的项目，并按项目对记忆进行范围限定。无需配置。

工作原理

MCP 服务启动时，会从你的工作目录读取 Git 远程地址：

~/Projects/acme-api/   →  git remote = github.com:you/acme-api.git
                       →  profile = "you/acme-api"
                       →  memories scoped to this project

~/Projects/my-cli/     →  git remote = github.com:you/my-cli.git
                       →  profile = "you/my-cli"
                       →  different project, different memories

范围限定内容

你说	会发生什么
“记住这个项目使用 Postgres 16”	以 profile: you/acme-api 存储（项目范围）
“记住我更喜欢 Bun，而不是 npm”	Agent 以 profile: global → null 存储（适用于所有项目）
“记住暂存环境的 URL 是 staging.acme.io”	以 profile: you/acme-api 存储（项目范围）

Agent 会根据上下文作出判断。用户偏好和行为反馈通常是全局的。项目详情和参考信息通常限定在项目范围内。

搜索时会看到什么

Working in acme-api:
  ✓ "Uses Postgres 16"              (profile: you/acme-api)
  ✓ "Prefers Bun over npm"          (profile: null — global)
  ✗ "Uses SQLite"                   (profile: you/my-cli — different project)

Working in my-cli:
  ✓ "Uses SQLite"                   (profile: you/my-cli)
  ✓ "Prefers Bun over npm"          (profile: null — global)
  ✗ "Uses Postgres 16"             (profile: you/acme-api — different project)

全局记忆始终会显示。项目记忆只会在对应项目中显示。

例外选项

Profile 值	含义
（省略）	自动限定到检测到的项目
"global"	明确设为全局——不限定项目
"all"	搜索／列出所有项目
"owner/other-repo"	明确指定其他项目

记忆的样子

每条记忆都是带有 YAML frontmatter 的 Markdown 文件。你可以在任何编辑器中打开它。

---
id: mem_a1b2c3d4e5f6
type: feedback
name: No database mocking in tests
description: Integration tests must use real database connections
profile: you/acme-api
importance: 3
tags: [testing, database]
created_at: "2026-04-14T10:30:00Z"
updated_at: "2026-04-14T14:22:00Z"
---

Do not mock the database in integration tests — use a real connection
to a test database.

**Why:** Mocked tests passed but the production migration failed because
the mock didn't reflect actual schema constraints.

**How to apply:** Use the test database helper (`createTestDb()`)
instead of jest mocks.

Git 日志的样子

$ git log --oneline
f4a2c1e remember: No database mocking in tests
b3d8e7a remember: TypeScript strict mode preference
a1c9f2b update: REST to GraphQL migration deadline
9e7d4c3 forget: Outdated staging URL
2f8a6b1 Initialize elefante vault

每次写入都会记录为 remember:。每次更新都会记录为 update:。每次删除都会记录为 forget:。你的记忆拥有清晰、可审计的历史记录。

保险库结构

~/.elefante/vault/
├── .elefante/
│   └── config.yaml              # Vault settings
├── memories/
│   ├── user/                    # Who the user is
│   │   └── mem_*.md
│   ├── feedback/                # How the agent should behave
│   │   └── mem_*.md
│   ├── project/                 # Active work context
│   │   └── mem_*.md
│   └── reference/               # External resource pointers
│       └── mem_*.md
├── profiles/
│   └── *.yaml                   # Named scopes for partitioning
└── index/
    ├── manifest.json            # All memory metadata (generated)
    └── search.json              # Search index (generated)

记忆类型

四种类型。刻意保持精简——小型分类体系有助于做好分类。

类型	存储内容	通常限定范围
user	关于你的事实——角色、偏好、专业知识	全局
feedback	Agent 行为指导——纠正、确认	全局
project	当前工作上下文——目标、截止日期、决策	项目
reference	外部引用——URL、仪表板、工具	项目

身份验证

Elefante 不会重新发明身份验证。它使用你已有的 Git 凭据。

解析顺序：

1. 本地 Git 凭据（SSH 密钥、macOS 钥匙串、凭据助手）
2. gh auth token（如果已安装 GitHub CLI）
3. ELEFANTE_GITHUB_TOKEN 环境变量
4. ~/.elefante/config.json 中的 token 字段

如果 git 或 gh 已通过身份验证，Elefante 无需任何配置即可运行。

CLI 参考

elefante init <repo-url>       Clone vault repo to ~/.elefante/vault/
elefante status                Vault status, sync state, memory count
elefante list [--type TYPE]    List memories with filters
elefante search <query>        Search by keyword
elefante read <id>             Read a specific memory
elefante add                   Create a memory
elefante delete <id>           Delete a memory
elefante sync                  Pull and push changes
elefante reindex               Rebuild search index
elefante mcp                   Start MCP stdio server

对比

Elefante 并不以检索质量为竞争优势，而是以数据所有权为竞争优势。

	Elefante	Claude/ChatGPT Memory	Mem0 / Zep
数据归你所有	由你掌控的 Git 仓库	由供应商掌控	可自托管或 SaaS
人类可读	Markdown 文件	否	否
版本历史	免费提供 Git 日志	否	否
兼容各种 Agent	任意 MCP Agent	单一供应商	是
无需基础设施	Git + 本地进程	不适用（托管式）	服务端 + 数据库
离线访问	本地克隆	否	否
自动限定项目范围	检测 Git 远程仓库	按对话区分	手动设置
语义搜索	尚未支持（计划中）	是	是

“为什么不使用 Obsidian + MCP 插件？”——Obsidian 是一款供人使用、Agent 可访问的工具。Elefante 是一款供 Agent 使用、人类可访问的工具。数据格式相同（Markdown + Git），设计重心不同。

协议

完整的协议规范——包括记忆模型、知识库结构、MCP 接口、并发模型、索引和安全注意事项——见 PROTOCOL.md。

许可证

MIT