Mengram

为 AI Agent 提供真正会学习的记忆

网站 · 获取 API 密钥 · 文档 · 控制台 · 示例

pip install mengram-ai   # the CLI; JS SDK: npm install mengram-ai

mengram try              # see what memory would know about you — local only,
                         # no account, nothing leaves your machine

from mengram import Mengram
m = Mengram(api_key="om-...")           # Free key → mengram.io

m.add([{"role": "user", "content": "I use Python and deploy to Railway"}])
m.search("tech stack")                  # → facts
m.ask("what's my tech stack?")          # → synthesized answer + citations
m.episodes(query="deployment")          # → events
m.procedures(query="deploy")            # → workflows that evolve from failures

原生支持多语言：用俄语、中文、西班牙语或日语提问，Mengram 可跨 23 种语言检索并作答（使用 Cohere 多语言嵌入 + 重排）。

一句话提示即可安装（适用于任何 AI 工具）

将以下内容粘贴到 Claude Desktop、Cursor、Codex、Claude Code 或 Windsurf 中，Agent 会阅读我们的安装指南，安装 SDK、配置 MCP 服务，并端到端验证整个流程。无需切换到终端。

Install Mengram for me. Fetch the canonical install guide at
https://mengram.io/agent-install.txt and follow it precisely.
My email is YOUR_EMAIL_HERE.

适用于任何具备 shell、文件编辑和网页抓取工具的 Agent。更喜欢手动操作？请参阅纯文本指南——它同样适合人类阅读。

Claude Code — 记忆在 /clear 和自动压缩后依然保留

持久记忆可在 /clear、自动压缩、切换设备和团队交接后继续保留——每次压缩后都会触发 SessionStart 钩子，重新注入上下文。摘要可能有损，但记忆不会。

# 1. Get a free key at https://mengram.io and save it once
mkdir -p ~/.mengram && echo '{"api_key": "om-your-key-here"}' > ~/.mengram/config.json

# 2. Install the plugin (hooks + MCP server + skill)
claude plugin marketplace add alibaizhanov/mengram
claude plugin install mengram@mengram

# 3. Skip the cold start — import your existing session history
#    (secrets are redacted on your machine before anything is uploaded)
mengram import claude-code

具体流程：

Session Start  →  Loads your cognitive profile (fires after /clear, compaction, and restarts)
Every Prompt   →  Searches past sessions for relevant context (auto-recall)
After Response →  Saves new knowledge in background (auto-save)
Before a Bash  →  If the command matches a learned workflow with a weak record, asks you first (policy gate, CLI hooks)
Before compact →  Writes the working state down — last prompts, files edited, last commands, where Claude left off (CLI hooks)
After compact  →  Puts that state back, verbatim, next to the host's summary — and tells you so in one line

无需手动保存。无需调用工具。Claude 就能知道你昨天做了什么——即使压缩已经吞掉了对话记录。

更喜欢通过 CLI 管理钩子，而不是使用插件？pip install mengram-ai && mengram setup 可通过 mengram hook install 完成相同设置。

Codex 和 Cursor 中共享同一份记忆

Codex 和 Cursor 会触发相同的生命周期事件，因此同一组钩子也会在这两个工具中运行——三者共享一份记忆。mengram setup 会在你的机器上找到它们并安装钩子；也可以逐个添加：

mengram hook install --codex      # ~/.codex/hooks.json: session context, recall on every prompt, compaction checkpoint, auto-save + task card
mengram hook install --cursor     # ~/.cursor/hooks.json: session context, compaction checkpoint (back on the next tool call), auto-save

Cursor 没有针对每条提示词的上下文钩子（beforeSubmitPrompt 只能允许或阻止），因此在对话过程中，需要通过 MCP 工具按需回忆；会话启动和上下文压缩则是自动的。

每条事实都会记录是由哪个工具在何时写入的，回忆时也会显示这些信息：deploys to Fly.io from main (codex, 2026-09-15)。每个钩子还会告诉服务它运行在哪种操作系统和工具下，因此，在你的 Mac 上记录的工作区路径不会传到 Linux 机器上的 Claude Code 会话中，关于 Cursor 设置的事实也不会传到 Codex 中——这些事实会被排除并计数（facts_left_out_for_host）。

从上次停下的地方继续任务——mengram resume

当 Agent 停止时，钩子会为仓库和分支写入一张任务卡：包含改动过的文件、最近运行的命令、最近一次测试及其运行所在的提交，以及 Agent 对任务的草稿、已完成事项和待办事项。该分支上的下一个会话——无论是明天的会话、另一个工作树中的另一个 Agent，还是另一台机器上的会话——都会首先收到这张任务卡，并会被告知自上次检查以来代码是否有变动。对于所在分支没有专属任务卡的会话（例如新建的 Orca 工作树），只会告知有任务卡存在，因为其他分支的任务卡通常对应的是另一个 Agent 的任务；如需查看，可运行 mengram resume：

$ mengram resume
[Mengram resume — where this task stands (2 h ago, from claude-code, branch main)]
Task (agent draft, not confirmed): prepare the Dify example for publication
Done:
  - three workflows assembled
  - save/recall round-trip checked through the API
Remaining:
  - import the workflows into Dify and check the model's answers
Last check: `python3 -m pytest -q tests/test_dify.py` → 4 passed in 0.31s
  The last check ran on 57cdde9; HEAD is now a1b2c3d (4 commits later). Its result describes the earlier state.
Files touched: examples/dify-support/workflow.yml
Sources: session 5d274778 · commit 57cdde9

mengram resume --open 会打开一个本地页面，用于修正任务卡、确认任务卡（已确认的文本不会重新起草）、选择其他任务，或复制上下文以用于新会话。任务卡保存在 ~/.mengram/resume/ 中，无需账户；只有任务、已完成事项和待办事项的草稿会使用大模型。

没有账户？将记忆保存在文件夹中

pip install mengram-ai
mengram local init ./memory --provider anthropic --api-key sk-ant-...   # or openai / ollama
mengram import claude-code --memory ./memory                             # seed it from your Claude Code sessions
mengram local map --memory ./memory --open                               # one page: who you are, what happened, what it learned
mengram hook install --memory ./memory                                   # the same four hooks, all local
mengram server --memory ./memory                                         # MCP for Claude Desktop, Cursor, any client

这个文件夹就是记忆：它是一棵由你拥有的 memfmt Markdown 文件树——git 可以显示差异，Obsidian 可以绘制图谱，memfmt validate 可以检查。它与云端一样，保留带结果的流程：版本、每个步骤的成功／失败计数、策略关卡，以及会隔离可能破坏其他工作流的修复的回归关卡。只有提取和失败后的修订需要大模型，而模型由你提供。内容不会过期，也不会索要密钥。文档。

本地搜索可匹配 Unicode 文本中的词语，包括俄语；它不使用嵌入，也不会翻译查询内容。多个 Mengram 会话通过文件夹锁协调写入，并合并互不冲突的新增内容。发生冲突的编辑需要重新加载，而不是覆盖另一个会话的内容。每个改动过的文件都会被原子替换，但整个文件夹并不是一个崩溃时具备原子性的事务，外部编辑器也不会参与此锁。

为什么选择 Mengram？

每种 AI 记忆工具都会存储事实。Mengram 存储 3 种记忆，并且在流程失败时持续演进。

30 秒快速开始

1. 安装

pip install mengram-ai

2. 设置 — 一条命令即可完成所有操作：创建账户、配置 Claude Code hooks、为检测到的工具（Cursor、Claude Desktop、Windsurf）配置 MCP、导入历史记录并进行往返检查

mengram setup

或者在 mengram.io 手动获取密钥，然后执行 export MENGRAM_API_KEY=om-...

3. 使用

from mengram import Mengram

m = Mengram(api_key="om-...")

# Add a conversation — auto-extracts facts, events, and workflows
m.add([
    {"role": "user", "content": "Deployed to Railway today. Build passed but forgot migrations — DB crashed. Fixed by adding a pre-deploy check."},
])

# Search across all 3 memory types at once
results = m.search_all("deployment issues")
# → {semantic: [...], episodic: [...], procedural: [...]}

# Upload a PDF — auto-extracts memories using vision AI
result = m.add_file("meeting-notes.pdf")
# → {"status": "accepted", "job_id": "job-...", "page_count": 12}

# Poll for completion
m.job_status(result["job_id"])

// Node.js — pass a file path
await m.addFile('./report.pdf');

// Browser — pass a File object from <input type="file">
await m.addFile(fileInput.files[0]);

# REST API
curl -X POST https://mengram.io/v1/add_file \
  -H "Authorization: Bearer om-..." \
  -F "[email protected]" \
  -F "user_id=default"

npm install mengram-ai

const { MengramClient } = require('mengram-ai');
const m = new MengramClient('om-...');

await m.add([{ role: 'user', content: 'Fixed OOM by adding Redis cache layer' }]);
const results = await m.searchAll('database issues');
// → { semantic: [...], episodic: [...], procedural: [...] }

# Add memory
curl -X POST https://mengram.io/v1/add \
  -H "Authorization: Bearer om-..." \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "I prefer dark mode and vim keybindings"}]}'

# Search all 3 types
curl -X POST https://mengram.io/v1/search/all \
  -H "Authorization: Bearer om-..." \
  -d '{"query": "user preferences"}'

3 种记忆类型

语义记忆 — 事实、偏好、知识

m.search("tech stack")
# → ["Uses Python 3.12", "Deploys to Railway", "PostgreSQL with pgvector"]

情景记忆 — 事件、决策、结果

m.episodes(query="deployment")
# → [{summary: "DB crashed due to missing migrations", outcome: "resolved", date: "2025-05-12"}]

程序性记忆 — 持续演进的工作流

Week 1:  "Deploy" → build → push → deploy
                                         ↓ FAILURE: forgot migrations
Week 2:  "Deploy" v2 → build → run migrations → push → deploy
                                                          ↓ FAILURE: OOM
Week 3:  "Deploy" v3 → build → run migrations → check memory → push → deploy ✅

当你报告失败时，这一过程会自动发生：

m.procedure_feedback(proc_id, success=False,
                     context="OOM error on step 3", failed_at_step=3)
# → Procedure evolves to v3 with new step added

每次由失败触发的修订都会记录哪项假设被证明是错误的，而不仅仅是哪个步骤出了问题；同时还会推导出一项前置条件，在回忆时与流程一同提供：

{
  "version": 3,
  "violated_assumption": "the build container had enough memory for a full build",
  "preconditions": ["check available memory before building"],
  "success_count": 11, "fail_count": 2
}

加载 v3 的 Agent 不会重复导致其产生的两个错误，并且知道在信任该工作流之前需要验证什么。

也可以完全自动化——只需添加对话，Mengram 就会检测失败并演进流程：

m.add([{"role": "user", "content": "Deploy failed again — OOM on the build step"}])
# → Episode created → linked to "Deploy" procedure → failure detected → v3 created

向记忆提问（内置 RAG）

m.ask() 会返回带引用的综合答案，而不是原始事实列表。 Mengram 会将你的查询转换为嵌入向量，检索最相关的事实，并使用 Cohere Chat 撰写有依据且带有原生来源归属的答案。

result = m.ask("what programming languages do I use?")

print(result["answer"])
# 'You use Python and Rust. Python is your daily language [1] and
#  Rust is your favorite [2]. You also know Java for enterprise
#  systems [3].'

for cit in result["citations"]:
    print(f'  "{cit["text"]}" → {cit["sources"][0]["fact"]}')
# "Python and Rust" → uses Python daily for backend development
# "favorite [2]"   → Rust is favorite language
# "Java"           → specializes in Java/Spring Boot

支持多语言：可使用 23 种语言中的任意一种提问，并以相同语言获得答案；引用会链接回以原始语言存储的事实。高级功能（Pro / Growth / Business）。

认知画像

一次 API 调用即可根据所有记忆生成系统提示词：

profile = m.get_profile()
# → "You are talking to Ali, a developer in Almaty. Uses Python, PostgreSQL,
#    and Railway. Recently debugged pgvector deployment. Prefers direct
#    communication and practical next steps."

将其插入任意大模型的系统提示词，即可立即实现个性化。

导入现有数据

解决冷启动问题：

mengram import chatgpt ~/Downloads/chatgpt-export.zip --cloud   # ChatGPT history
mengram import obsidian ~/Documents/MyVault --cloud              # Obsidian vault
mengram import files notes/*.md --cloud                          # Any text/markdown

集成

mengram hook install

{
  "mcpServers": {
    "mengram": {
      "command": "mengram",
      "args": ["server", "--cloud"],
      "env": { "MENGRAM_API_KEY": "om-..." }
    }
  }
}

from langchain_mengram import (
    MengramRetriever,
    MengramChatMessageHistory,
)

retriever = MengramRetriever(api_key="om-...")
docs = retriever.invoke("deployment issues")

from integrations.crewai import create_mengram_tools

tools = create_mengram_tools(api_key="om-...")
# → 5 tools: search, remember, profile,
#   save_workflow, workflow_feedback

agent = Agent(role="Support", tools=tools)

openclaw plugins install openclaw-mengram

mengram hook install                        # auto-recall + auto-save in Claude Code
mengram import chatgpt export.zip --cloud   # bring your ChatGPT history
mengram rules --format claude_md            # CLAUDE.md from what memory knows
mengram local search "deployment"           # search a local memory folder

{
  "mcp_servers": [{
    "type": "url",
    "name": "mengram",
    "url": "https://mengram.io/mcp/sse"
  }]
}

POST https://mengram.io/v1/add
POST https://mengram.io/v1/search

多用户隔离

一个 API 密钥，多个用户 — 每个用户只能查看自己的数据：

m.add([...], user_id="alice")
m.add([...], user_id="bob")

m.search_all("preferences", user_id="alice")  # Only Alice's memories
m.get_profile(user_id="alice")                 # Alice's cognitive profile

异步客户端

基于 httpx 构建的非阻塞 Python 客户端：

from mengram import AsyncMengram

async with AsyncMengram() as m:
    await m.add([{"role": "user", "content": "I use async/await"}])
    results = await m.search("async")
    profile = await m.get_profile()

使用 pip install mengram-ai[async] 安装。

元数据筛选

按元数据筛选搜索结果：

results = m.search("config", filters={"agent_id": "support-bot", "app_id": "prod"})

Webhook

在记忆发生变化时接收通知：

m.create_webhook(
    url="https://your-app.com/hook",
    event_types=["memory_add", "memory_update"],
)

Agent 模板

克隆、设置 API 密钥，5 分钟内即可运行：

cd examples/devops-agent && pip install -r requirements.txt
export MENGRAM_API_KEY=om-...
python main.py

与 AI Agent 搭配使用

Mengram 可作为自主 Agent 的持久化记忆后端。你的 Agent 会存储学到的内容，并在下次运行时检索，让它随时间不断变得更智能。

from mengram import Mengram

m = Mengram(api_key="om-...")

# Agent completes a task → store what happened
m.add([
    {"role": "user", "content": "Apply to Acme Corp on Greenhouse"},
    {"role": "assistant", "content": "Applied successfully. Had to use React Select workaround for dropdowns."},
])
# → Extracts: fact ("applied to Acme Corp"), episode ("Greenhouse application"),
#   procedure ("React Select dropdown workaround")

# Next run → agent recalls what worked before
context = m.search_all("Greenhouse application tips")
# → Returns past procedures, failures, and successful strategies

# Report outcome → procedures evolve
m.procedure_feedback(proc_id, success=False,
                     context="Dropdown fix stopped working")
# → Procedure auto-evolves to a new version

兼容任何 Agent 框架 — CrewAI、LangChain、AutoGPT、自定义循环。Agent 只需在执行操作后调用 add()，并在作出决策前调用 search()。

自托管（Ollama）

使用 Ollama 在本地运行时，请使用参数量 8B+ 且上下文窗口 8K+ 的模型。提取提示词约为 4,000 个 token——较小的模型会产生幻觉，或将示例与真实数据混淆。

API 参考

完整的交互式文档：mengram.io/docs

配额标头

每个通过身份验证的响应都包含用量标头：

SDK 通过 .quota 提供这些信息：

m.search("test")
print(m.quota)  # {"add": {"used": 5, "limit": 30}, "search": {"used": 12, "limit": 100}}

社区

• GitHub Issues — Bug 报告、功能请求
• GitHub Discussions — 分享你的使用场景、提出问题
• API Docs — 交互式 Swagger UI
• Examples — 可直接运行的 Agent 模板

Star 历史

许可证

Apache 2.0 — 可免费用于商业用途。