\n\n\n \n \n\n\n### Give your AI agents memory that actually learns\n\n[](https://github.com/alibaizhanov/mengram/stargazers)\n[](https://pypi.org/project/mengram-ai/)\n[](https://www.npmjs.com/package/mengram-ai)\n[](LICENSE)\n[](https://pypi.org/project/mengram-ai/)\n[](https://github.com/alibaizhanov/mengram/commits/main)\n\n**[Website](https://mengram.io)** · **[Get API Key](https://mengram.io/#signup)** · **[Docs](https://mengram.io/docs)** · **[Console](https://mengram.io/dashboard)** · **[Examples](examples/)**\n\n
\n\n```bash\npip install mengram-ai # or: npm install mengram-ai\n\nmengram try # see what memory would know about you — local only,\n # no account, nothing leaves your machine\n```\n\n```python\nfrom mengram import Mengram\nm = Mengram(api_key=\"om-...\") # Free key → mengram.io\n\nm.add([{\"role\": \"user\", \"content\": \"I use Python and deploy to Railway\"}])\nm.search(\"tech stack\") # → facts\nm.ask(\"what's my tech stack?\") # → synthesized answer + citations\nm.episodes(query=\"deployment\") # → events\nm.procedures(query=\"deploy\") # → workflows that evolve from failures\n```\n\nNative multilingual: ask in Russian, Chinese, Spanish, Japanese — Mengram retrieves and answers across 23 languages (Cohere multilingual embeddings + rerank).\n\n---\n\n## Install in one prompt (any AI tool)\n\nPaste this into Claude Desktop, Cursor, Codex, Claude Code, or Windsurf — the agent reads our [setup guide](https://mengram.io/agent-install.txt), installs the SDK, configures the MCP server, and verifies the round-trip end-to-end. **No terminal context-switching.**\n\n```\nInstall Mengram for me. Fetch the canonical install guide at\nhttps://mengram.io/agent-install.txt and follow it precisely.\nMy email is YOUR_EMAIL_HERE.\n```\n\nWorks in any agent with shell + file-edit + web-fetch tools. Prefer doing it manually? See the [plain-text guide](https://mengram.io/agent-install.txt) — it's structured for human eyes too.\n\n---\n\n## Claude Code — Memory That Survives /clear AND Auto-Compaction\n\nPersistent 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.\n\n```bash\n# 1. Get a free key at https://mengram.io and save it once\nmkdir -p ~/.mengram && echo '{\"api_key\": \"om-your-key-here\"}' > ~/.mengram/config.json\n\n# 2. Install the plugin (hooks + MCP server + skill)\nclaude plugin marketplace add alibaizhanov/mengram\nclaude plugin install mengram@mengram\n\n# 3. Skip the cold start — import your existing session history\n# (secrets are redacted on your machine before anything is uploaded)\nmengram import claude-code\n```\n\nWhat happens:\n\n```\nSession Start → Loads your cognitive profile (fires after /clear, compaction, and restarts)\nEvery Prompt → Searches past sessions for relevant context (auto-recall)\nAfter Response → Saves new knowledge in background (auto-save)\nBefore a Bash → If the command matches a learned workflow with a weak record, asks you first (policy gate, CLI hooks)\n```\n\nNo manual saves. No tool calls. Claude just knows what you worked on yesterday — even after compaction ate the transcript.\n\nPrefer CLI-managed hooks instead of the plugin? `pip install mengram-ai && mengram setup` does the same via `mengram hook install`.\n\n### No account? Keep the memory in a folder\n\n```bash\npip install mengram-ai\nmengram local init ./memory --provider anthropic --api-key sk-ant-... # or openai / ollama\nmengram import claude-code --memory ./memory # seed it from your Claude Code sessions\nmengram local map --memory ./memory --open # one page: who you are, what happened, what it learned\nmengram hook install --memory ./memory # the same four hooks, all local\nmengram server --memory ./memory # MCP for Claude Desktop, Cursor, any client\n```\n\nThe folder is the memory: a [memfmt](https://github.com/alibaizhanov/memfmt) tree of Markdown you own — git diffs it, Obsidian draws it, `memfmt validate` checks it. Same procedures-with-outcomes as the cloud: versions, success/fail counts per step, the policy gate, and the regression gate that quarantines a fix that would break another workflow. Only extraction and a failure revision need a model, and that one you bring. Nothing expires and nothing asks for a key. [Docs](https://docs.mengram.io/local-mode).\n\n---\n\n## Why Mengram?\n\nEvery AI memory tool stores facts. Mengram stores **3 types of memory** — and procedures **evolve when they fail**.\n\n| | Mengram | claude-mem | Mem0 | Zep | Letta |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Semantic memory (facts, preferences) | **Yes** | Yes | Yes | Yes | Yes |\n| **Episodic memory (events, decisions)** | **Yes** | Partial | No | No | Partial |\n| **Procedural memory (workflows)** | **Yes** | No | No | No | No |\n| **Procedures evolve from failures** | **Yes** | No | No | No | No |\n| **Cognitive Profile** | **Yes** | No | No | No | No |\n| **Native multilingual retrieval (23 languages)** | **Yes** | Partial | No | No | No |\n| **Ask & Citations (synthesized answer)** | **Yes** | No | No | No | No |\n| Multi-user isolation | **Yes** | No | Yes | Yes | No |\n| Knowledge graph | **Yes** | No | Yes | Yes | Yes |\n| Claude Code hooks (auto-save/recall) | **Yes** | **Yes** | No | No | No |\n| MCP server | **Yes** | Yes | Yes | Yes | Yes |\n| LangChain + CrewAI integrations | **Yes** | No | Partial | Partial | Partial |\n| **Import Claude Code history / ChatGPT / Obsidian** | **Yes** | No | No | No | No |\n| Pricing | **Free tier** | Free OSS (+cloud backup) | $19-249/mo | Enterprise | Self-host |\n\n## Get Started in 30 Seconds\n\n**1. Install**\n\n```bash\npip install mengram-ai\n```\n\n**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\n\n```bash\nmengram setup\n```\n\nOr get a key manually at [mengram.io](https://mengram.io/#signup) and `export MENGRAM_API_KEY=om-...`\n\n**3. Use**\n\n```python\nfrom mengram import Mengram\n\nm = Mengram(api_key=\"om-...\")\n\n# Add a conversation — auto-extracts facts, events, and workflows\nm.add([\n {\"role\": \"user\", \"content\": \"Deployed to Railway today. Build passed but forgot migrations — DB crashed. Fixed by adding a pre-deploy check.\"},\n])\n\n# Search across all 3 memory types at once\nresults = m.search_all(\"deployment issues\")\n# → {semantic: [...], episodic: [...], procedural: [...]}\n```\n\n\nFile Upload (PDF, DOCX, TXT, MD)\n\n```python\n# Upload a PDF — auto-extracts memories using vision AI\nresult = m.add_file(\"meeting-notes.pdf\")\n# → {\"status\": \"accepted\", \"job_id\": \"job-...\", \"page_count\": 12}\n\n# Poll for completion\nm.job_status(result[\"job_id\"])\n```\n\n```javascript\n// Node.js — pass a file path\nawait m.addFile('./report.pdf');\n\n// Browser — pass a File object from \nawait m.addFile(fileInput.files[0]);\n```\n\n```bash\n# REST API\ncurl -X POST https://mengram.io/v1/add_file \\\n -H \"Authorization: Bearer om-...\" \\\n -F \"file=@meeting-notes.pdf\" \\\n -F \"user_id=default\"\n```\n\n\n\n\nJavaScript / TypeScript\n\n```bash\nnpm install mengram-ai\n```\n\n```javascript\nconst { MengramClient } = require('mengram-ai');\nconst m = new MengramClient('om-...');\n\nawait m.add([{ role: 'user', content: 'Fixed OOM by adding Redis cache layer' }]);\nconst results = await m.searchAll('database issues');\n// → { semantic: [...], episodic: [...], procedural: [...] }\n```\n\n\n\n\nREST API (curl)\n\n```bash\n# Add memory\ncurl -X POST https://mengram.io/v1/add \\\n -H \"Authorization: Bearer om-...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"messages\": [{\"role\": \"user\", \"content\": \"I prefer dark mode and vim keybindings\"}]}'\n\n# Search all 3 types\ncurl -X POST https://mengram.io/v1/search/all \\\n -H \"Authorization: Bearer om-...\" \\\n -d '{\"query\": \"user preferences\"}'\n```\n\n\n\n## 3 Memory Types\n\n### Semantic — facts, preferences, knowledge\n\n```python\nm.search(\"tech stack\")\n# → [\"Uses Python 3.12\", \"Deploys to Railway\", \"PostgreSQL with pgvector\"]\n```\n\n### Episodic — events, decisions, outcomes\n\n```python\nm.episodes(query=\"deployment\")\n# → [{summary: \"DB crashed due to missing migrations\", outcome: \"resolved\", date: \"2025-05-12\"}]\n```\n\n### Procedural — workflows that evolve\n\n```\nWeek 1: \"Deploy\" → build → push → deploy\n ↓ FAILURE: forgot migrations\nWeek 2: \"Deploy\" v2 → build → run migrations → push → deploy\n ↓ FAILURE: OOM\nWeek 3: \"Deploy\" v3 → build → run migrations → check memory → push → deploy ✅\n```\n\nThis happens **automatically** when you report failures:\n\n```python\nm.procedure_feedback(proc_id, success=False,\n context=\"OOM error on step 3\", failed_at_step=3)\n# → Procedure evolves to v3 with new step added\n```\n\nEvery 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:\n\n```json\n{\n \"version\": 3,\n \"violated_assumption\": \"the build container had enough memory for a full build\",\n \"preconditions\": [\"check available memory before building\"],\n \"success_count\": 11, \"fail_count\": 2\n}\n```\n\nAn agent loading v3 doesn't repeat the two mistakes that produced it — and knows what to verify before trusting the workflow.\n\nOr **fully automatic** — just add conversations and Mengram detects failures and evolves procedures:\n\n```python\nm.add([{\"role\": \"user\", \"content\": \"Deploy failed again — OOM on the build step\"}])\n# → Episode created → linked to \"Deploy\" procedure → failure detected → v3 created\n```\n\n## Ask Your Memory (RAG built-in)\n\n`m.ask()` returns a synthesized answer with citations — not a raw fact list.\nMengram embeds your query, retrieves the top relevant facts, and uses\nCohere Chat to write a grounded answer with native source attribution.\n\n```python\nresult = m.ask(\"what programming languages do I use?\")\n\nprint(result[\"answer\"])\n# 'You use Python and Rust. Python is your daily language [1] and\n# Rust is your favorite [2]. You also know Java for enterprise\n# systems [3].'\n\nfor cit in result[\"citations\"]:\n print(f' \"{cit[\"text\"]}\" → {cit[\"sources\"][0][\"fact\"]}')\n# \"Python and Rust\" → uses Python daily for backend development\n# \"favorite [2]\" → Rust is favorite language\n# \"Java\" → specializes in Java/Spring Boot\n```\n\nMultilingual: 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).\n\n## Cognitive Profile\n\nOne API call generates a system prompt from all memories:\n\n```python\nprofile = m.get_profile()\n# → \"You are talking to Ali, a developer in Almaty. Uses Python, PostgreSQL,\n# and Railway. Recently debugged pgvector deployment. Prefers direct\n# communication and practical next steps.\"\n```\n\nInsert into any LLM's system prompt for instant personalization.\n\n## Import Existing Data\n\nKill the cold-start problem:\n\n```bash\nmengram import chatgpt ~/Downloads/chatgpt-export.zip --cloud # ChatGPT history\nmengram import obsidian ~/Documents/MyVault --cloud # Obsidian vault\nmengram import files notes/*.md --cloud # Any text/markdown\n```\n\n## Integrations\n\n
\n
\n
\n\n**Claude Code** — Auto-memory hooks\n\n```bash\nmengram hook install\n```\n\n4 hooks: profile on start, recall on every prompt, save after responses, and a policy gate before workflow-shaped Bash commands.\n\n**Policy gate.** Outcome history changes what the agent may do, not only how results rank. When a `git push`, `deploy`, `migrate`, `kubectl`, `rm -rf` … matches a learned workflow that is `untested`, inherits its record from an earlier version (`61% expected`), or sits below the bar (`58% reliable`, default 70), the hook answers `ask`: you see why, Claude gets the steps on record, nothing runs on the agent's say-so. A proven workflow stays silent. Works against the cloud, or fully offline against a [memfmt](https://github.com/alibaizhanov/memfmt) folder with `MENGRAM_MEMORY_DIR=./memory`. Only workflow-shaped commands trigger a lookup (one search each); `ls` and `cat` never do. Tune with `MENGRAM_POLICY_MIN_RELIABLE=80`, `MENGRAM_POLICY_PATTERN='\\bmake\\b'`; skip with `mengram hook install --no-policy`. The memory can ask; it never denies.\n\n[Docs](https://mengram.io/docs/claude-code)\n\n
\n\n**n8n** — HTTP nodes for any workflow\n\n```\nPOST https://mengram.io/v1/add\nPOST https://mengram.io/v1/search\n```\n\nNo code needed — drag and drop memory into any n8n workflow.\n\n[Docs](https://mengram.io/docs/n8n)\n\n
\n
\n
\n\n## Multi-User Isolation\n\nOne API key, many users — each sees only their own data:\n\n```python\nm.add([...], user_id=\"alice\")\nm.add([...], user_id=\"bob\")\n\nm.search_all(\"preferences\", user_id=\"alice\") # Only Alice's memories\nm.get_profile(user_id=\"alice\") # Alice's cognitive profile\n```\n\n## Async Client\n\nNon-blocking Python client built on httpx:\n\n```python\nfrom mengram import AsyncMengram\n\nasync with AsyncMengram() as m:\n await m.add([{\"role\": \"user\", \"content\": \"I use async/await\"}])\n results = await m.search(\"async\")\n profile = await m.get_profile()\n```\n\nInstall with `pip install mengram-ai[async]`.\n\n## Metadata Filters\n\nFilter search results by metadata:\n\n```python\nresults = m.search(\"config\", filters={\"agent_id\": \"support-bot\", \"app_id\": \"prod\"})\n```\n\n## Webhooks\n\nGet notified when memories change:\n\n```python\nm.create_webhook(\n url=\"https://your-app.com/hook\",\n event_types=[\"memory_add\", \"memory_update\"],\n)\n```\n\n## Agent Templates\n\nClone, set API key, run in 5 minutes:\n\n| Template | Stack | What it shows |\n|---|---|---|\n| **[DevOps Agent](examples/devops-agent/)** | Python SDK | Procedures that evolve from deployment failures |\n| **[Customer Support](examples/customer-support-agent/)** | CrewAI | Agent with 5 memory tools, remembers returning customers |\n| **[Personal Assistant](examples/personal-assistant/)** | LangChain | Cognitive profile + auto-saving chat history |\n\n```bash\ncd examples/devops-agent && pip install -r requirements.txt\nexport MENGRAM_API_KEY=om-...\npython main.py\n```\n\n## Use with AI Agents\n\nMengram 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.\n\n```python\nfrom mengram import Mengram\n\nm = Mengram(api_key=\"om-...\")\n\n# Agent completes a task → store what happened\nm.add([\n {\"role\": \"user\", \"content\": \"Apply to Acme Corp on Greenhouse\"},\n {\"role\": \"assistant\", \"content\": \"Applied successfully. Had to use React Select workaround for dropdowns.\"},\n])\n# → Extracts: fact (\"applied to Acme Corp\"), episode (\"Greenhouse application\"),\n# procedure (\"React Select dropdown workaround\")\n\n# Next run → agent recalls what worked before\ncontext = m.search_all(\"Greenhouse application tips\")\n# → Returns past procedures, failures, and successful strategies\n\n# Report outcome → procedures evolve\nm.procedure_feedback(proc_id, success=False,\n context=\"Dropdown fix stopped working\")\n# → Procedure auto-evolves to a new version\n```\n\nWorks with any agent framework — CrewAI, LangChain, AutoGPT, custom loops. The agent just calls `add()` after actions and `search()` before decisions.\n\n## Self-Hosted (Ollama)\n\nWhen 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.\n\n| Model | Parameters | Works? |\n|-------|-----------|--------|\n| `llama3.1:8b` | 8B | Yes |\n| `mistral:7b` | 7B | Yes |\n| `gemma2:9b` | 9B | Yes |\n| `llama3.1:70b` | 70B | Best |\n| `phi4-mini:3.8b` | 3.8B | No — context too small |\n\n## API Reference\n\n| Endpoint | Description |\n|---|---|\n| `POST /v1/add` | Add memories (auto-extracts all 3 types) |\n| `POST /v1/add_text` | Add memories from plain text |\n| `POST /v1/add_file` | Upload file (PDF, DOCX, TXT, MD) — vision AI extraction |\n| `POST /v1/search` | Semantic search |\n| `POST /v1/search/all` | Unified search (semantic + episodic + procedural) |\n| `GET /v1/episodes/search` | Search events and decisions |\n| `GET /v1/procedures/search` | Search workflows |\n| `PATCH /v1/procedures/{id}/feedback` | Report outcome — triggers evolution |\n| `GET /v1/procedures/{id}/history` | Version history + evolution log |\n| `GET /v1/profile` | Cognitive Profile |\n| `GET /v1/triggers` | Smart Triggers (reminders, contradictions, patterns) |\n| `POST /v1/agents/run` | Memory agents (Curator, Connector, Digest) |\n| `GET /v1/me` | Account info |\n\nFull interactive docs: **[mengram.io/docs](https://mengram.io/docs)**\n\n### Quota Headers\n\nEvery authenticated response includes usage headers:\n\n| Header | Description |\n|--------|-------------|\n| `X-Quota-Add-Used` | Add calls used this month |\n| `X-Quota-Add-Limit` | Add calls allowed this month |\n| `X-Quota-Search-Used` | Search calls used this month |\n| `X-Quota-Search-Limit` | Search calls allowed this month |\n\nSDKs expose this via `.quota`:\n\n```python\nm.search(\"test\")\nprint(m.quota) # {\"add\": {\"used\": 5, \"limit\": 30}, \"search\": {\"used\": 12, \"limit\": 100}}\n```\n\n## Community\n\n- **[GitHub Issues](https://github.com/alibaizhanov/mengram/issues)** — bug reports, feature requests\n- **[GitHub Discussions](https://github.com/alibaizhanov/mengram/discussions)** — show your use case, ask questions\n- **[API Docs](https://mengram.io/docs)** — interactive Swagger UI\n- **[Examples](examples/)** — ready-to-run agent templates\n\n## Star History\n\n\n \n \n \n \n \n\n\n## License\n\nApache 2.0 — free for commercial use.\n\n---\n\n
\n\n**[Get your free API key](https://mengram.io/#signup)** · Built by **[Ali Baizhanov](https://github.com/alibaizhanov)** · **[mengram.io](https://mengram.io)**\n\n
![\"Mengram\"](\"https://img.shields.io/badge/Mengram-a855f7?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjAgMTIwIj48cGF0aCBkPSJNNjAgMTYgUTkyIDE2IDk2IDQ4IFExMDAgNzggNzIgODggUTUwIDk2IDM4IDc2IFEyNiA1OCA0NiA0NiBRNjIgMzggNzAgNTIgUTc2IDY0IDYyIDY4IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PGNpcmNsZSBjeD0iNjIiIGN5PSI2OCIgcj0iOCIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg==\"){kind=icon}
\n