mengram

<div align="center">

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Mengram-a855f7?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjAgMTIwIj48cGF0aCBkPSJNNjAgMTYgUTkyIDE2IDk2IDQ4IFExMDAgNzggNzIgODggUTUwIDk2IDM4IDc2IFEyNiA1OCA0NiA0NiBRNjIgMzggNzAgNTIgUTc2IDY0IDYyIDY4IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PGNpcmNsZSBjeD0iNjIiIGN5PSI2OCIgcj0iOCIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg=="> <img alt="Mengram" src="https://img.shields.io/badge/Mengram-a855f7?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjAgMTIwIj48cGF0aCBkPSJNNjAgMTYgUTkyIDE2IDk2IDQ4IFExMDAgNzggNzIgODggUTUwIDk2IDM4IDc2IFEyNiA1OCA0NiA0NiBRNjIgMzggNzAgNTIgUTc2IDY0IDYyIDY4IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PGNpcmNsZSBjeD0iNjIiIGN5PSI2OCIgcj0iOCIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg=="> </picture>

Give your AI agents memory that actually learns

     

Website · Get API Key · Docs · Console · Examples

</div>

pip install mengram-ai   # or: 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

Native multilingual: ask in Russian, Chinese, Spanish, Japanese — Mengram retrieves and answers across 23 languages (Cohere multilingual embeddings + rerank).

---

Install in one prompt (any AI tool)

Paste this into Claude Desktop, Cursor, Codex, Claude Code, or Windsurf — the agent reads our setup guide, installs the SDK, configures the MCP server, and verifies the round-trip end-to-end. No terminal context-switching.

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.

Works in any agent with shell + file-edit + web-fetch tools. Prefer doing it manually? See the plain-text guide — it's structured for human eyes too.

---

Claude Code — Memory That Survives /clear AND Auto-Compaction

Persistent memory that survives /clear, auto-compaction, machine switches, and team handoffs — the SessionStart hook fires after every compact and re-injects your context. The summary can be lossy; the memory isn't.

# 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

What happens:

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)

No manual saves. No tool calls. Claude just knows what you worked on yesterday — even after compaction ate the transcript.

Prefer CLI-managed hooks instead of the plugin? pip install mengram-ai && mengram setup does the same via mengram hook install.

---

Why Mengram?

Every AI memory tool stores facts. Mengram stores 3 types of memory — and procedures evolve when they fail.

| | Mengram | claude-mem | Mem0 | Zep | Letta | |---|:---:|:---:|:---:|:---:|:---:| | Semantic memory (facts, preferences) | Yes | Yes | Yes | Yes | Yes | | Episodic memory (events, decisions) | Yes | Partial | No | No | Partial | | Procedural memory (workflows) | Yes | No | No | No | No | | Procedures evolve from failures | Yes | No | No | No | No | | Cognitive Profile | Yes | No | No | No | No | | Native multilingual retrieval (23 languages) | Yes | Partial | No | No | No | | Ask & Citations (synthesized answer) | Yes | No | No | No | No | | Multi-user isolation | Yes | No | Yes | Yes | No | | Knowledge graph | Yes | No | Yes | Yes | Yes | | Claude Code hooks (auto-save/recall) | Yes | Yes | No | No | No | | MCP server | Yes | Yes | Yes | Yes | Yes | | LangChain + CrewAI integrations | Yes | No | Partial | Partial | Partial | | Import Claude Code history / ChatGPT / Obsidian | Yes | No | No | No | No | | Pricing | Free tier | Free OSS (+cloud backup) | $19-249/mo | Enterprise | Self-host |

Get Started in 30 Seconds

1. Install

pip install mengram-ai

2. Setup — one command does everything: account, Claude Code hooks, MCP configs for detected tools (Cursor, Claude Desktop, Windsurf), history import, and a round-trip check

mengram setup

Or get a key manually at mengram.io and export MENGRAM_API_KEY=om-...

3. Use

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: [...]}

<details> <summary><b>File Upload (PDF, DOCX, TXT, MD)</b></summary>

# 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 "file=@meeting-notes.pdf" \
  -F "user_id=default"

</details>

<details> <summary><b>JavaScript / TypeScript</b></summary>

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: [...] }

</details>

<details> <summary><b>REST API (curl)</b></summary>

# 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"}'

</details>

3 Memory Types

Semantic — facts, preferences, knowledge

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

Episodic — events, decisions, outcomes

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

Procedural — workflows that evolve

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 ✅

This happens automatically when you report failures:

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

Every failure-driven revision records which assumption turned out false — not just which step broke — and derives a precondition that travels with the procedure at recall time:

{
  "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
}

An agent loading v3 doesn't repeat the two mistakes that produced it — and knows what to verify before trusting the workflow.

Or fully automatic — just add conversations and Mengram detects failures and evolves procedures:

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

Ask Your Memory (RAG built-in)

m.ask() returns a synthesized answer with citations — not a raw fact list. Mengram embeds your query, retrieves the top relevant facts, and uses Cohere Chat to write a grounded answer with native source attribution.

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

Multilingual: ask in any of 23 languages, get an answer in the same language with citations linking back to facts in the original language they were stored. Premium feature (Pro / Growth / Business).

Cognitive Profile

One API call generates a system prompt from all memories:

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."

Insert into any LLM's system prompt for instant personalization.

Import Existing Data

Kill the cold-start problem:

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

Integrations

<table> <tr> <td width="50%">

Claude Code — Auto-memory hooks

mengram hook install

3 hooks: profile on start, recall on every prompt, save after responses. Zero manual effort.

Docs

</td> <td width="50%">

MCP Server — Claude Desktop, Cursor, Codex, Windsurf, Cline

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

30 tools for memory management.

</td> </tr> <tr> <td width="50%">

LangChain — pip install langchain-mengram

from langchain_mengram import (
    MengramRetriever,
    MengramChatMessageHistory,
)

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

</td> <td width="50%">

CrewAI

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)

</td> </tr> <tr> <td width="50%">

OpenClaw

openclaw plugins install openclaw-mengram

Auto-recall before every turn, auto-capture after. 12 tools, slash commands, Graph RAG.

GitHub · npm

</td> <td width="50%">

CLI — Full command-line interface

mengram search "deployment" --cloud
mengram profile --cloud
mengram import chatgpt export.zip --cloud
mengram hook install

Docs

</td> </tr> <tr> <td width="50%">

Claude Managed Agents — MCP memory for hosted agents

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

30 memory tools via MCP. Docs

</td> <td width="50%">

n8n — HTTP nodes for any workflow

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

No code needed — drag and drop memory into any n8n workflow.

Docs

</td> </tr> </table>

Multi-User Isolation

One API key, many users — each sees only their own data:

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

Async Client

Non-blocking Python client built on httpx:

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()

Install with pip install mengram-ai[async].

Metadata Filters

Filter search results by metadata:

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

Webhooks

Get notified when memories change:

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

Agent Templates

Clone, set API key, run in 5 minutes:

| Template | Stack | What it shows | |---|---|---| | DevOps Agent | Python SDK | Procedures that evolve from deployment failures | | Customer Support | CrewAI | Agent with 5 memory tools, remembers returning customers | | Personal Assistant | LangChain | Cognitive profile + auto-saving chat history |

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

Use with AI Agents

Mengram works as a persistent memory backend for autonomous agents. Your agent stores what it learns, and recalls it on the next run — getting smarter over time.

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

Works with any agent framework — CrewAI, LangChain, AutoGPT, custom loops. The agent just calls add() after actions and search() before decisions.

Self-Hosted (Ollama)

When running locally with Ollama, use models with 8B+ parameters and 8K+ context window. The extraction prompt is ~4,000 tokens — smaller models will hallucinate or mix examples with real data.

| Model | Parameters | Works? | |-------|-----------|--------| | llama3.1:8b | 8B | Yes | | mistral:7b | 7B | Yes | | gemma2:9b | 9B | Yes | | llama3.1:70b | 70B | Best | | phi4-mini:3.8b | 3.8B | No — context too small |

API Reference

| Endpoint | Description | |---|---| | POST /v1/add | Add memories (auto-extracts all 3 types) | | POST /v1/add_text | Add memories from plain text | | POST /v1/add_file | Upload file (PDF, DOCX, TXT, MD) — vision AI extraction | | POST /v1/search | Semantic search | | POST /v1/search/all | Unified search (semantic + episodic + procedural) | | GET /v1/episodes/search | Search events and decisions | | GET /v1/procedures/search | Search workflows | | PATCH /v1/procedures/{id}/feedback | Report outcome — triggers evolution | | GET /v1/procedures/{id}/history | Version history + evolution log | | GET /v1/profile | Cognitive Profile | | GET /v1/triggers | Smart Triggers (reminders, contradictions, patterns) | | POST /v1/agents/run | Memory agents (Curator, Connector, Digest) | | GET /v1/me | Account info |

Full interactive docs: mengram.io/docs

Quota Headers

Every authenticated response includes usage headers:

| Header | Description | |--------|-------------| | X-Quota-Add-Used | Add calls used this month | | X-Quota-Add-Limit | Add calls allowed this month | | X-Quota-Search-Used | Search calls used this month | | X-Quota-Search-Limit | Search calls allowed this month |

SDKs expose this via .quota:

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

Community

• GitHub Issues — bug reports, feature requests
• GitHub Discussions — show your use case, ask questions
• API Docs — interactive Swagger UI
• Examples — ready-to-run agent templates

Star History

<a href="https://star-history.com/#alibaizhanov/mengram&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=alibaizhanov/mengram&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=alibaizhanov/mengram&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=alibaizhanov/mengram&type=Date" /> </picture> </a>

License

Apache 2.0 — free for commercial use.

---

<div align="center">

Get your free API key · Built by Ali Baizhanov · mengram.io

</div>