Skip to content
Back to search

mengram

Human-like memory for AI agents — semantic, episodic & procedural. Experience-driven procedures that learn from failures. Free API, Python & JS SDKs, LangChain, CrewAI & OpenClaw integrations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alibaizhanov--mengram/badge.svg)](/listings/alibaizhanov--mengram)

HTML

<a href="/listings/alibaizhanov--mengram"><img src="/api/listings/alibaizhanov--mengram/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Paste 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.**

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](https://mengram.io/agent-install.txt) — it's structured for human eyes too.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 37 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "mengram",
  3. "owner": {
  4. "name": "Ali Baizhanov",
  5. "email": "ali@mengram.io",
  6. "url": "https://mengram.io"
  7. },
  8. "plugins": [
  9. {
  10. "name": "mengram",
  11. "version": "0.1.4",
  12. "description": "Persistent memory for Claude Code that survives /clear, machine switches, and team handoffs. Hosted memory backend with hybrid retrieval (vector + BM25 + RRF), Ebbinghaus temporal decay, and importance weighting. Same memory available across Claude Code, Cursor, Codex, and ChatGPT.",
  13. "source": {
  14. "source": "git-subdir",
  15. "url": "alibaizhanov/mengram",
  16. "path": "integrations/claude-code-plugin"
  17. },
  18. "author": {
  19. "name": "Ali Baizhanov",
  20. "email": "ali@mengram.io",
  21. "url": "https://mengram.io"
  22. },
  23. "homepage": "https://mengram.io",
  24. "license": "Apache-2.0",
  25. "category": "productivity",
  26. "keywords": [
  27. "memory",
  28. "mcp",
  29. "context",
  30. "cross-device",
  31. "hybrid-retrieval",
  32. "anthropic",
  33. "persistence"
  34. ]
  35. }
  36. ]
  37. }
README.md · README · 665 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <picture>
  3. <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==">
  4. <img alt="Mengram" src="https://img.shields.io/badge/Mengram-a855f7?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjAgMTIwIj48cGF0aCBkPSJNNjAgMTYgUTkyIDE2IDk2IDQ4IFExMDAgNzggNzIgODggUTUwIDk2IDM4IDc2IFEyNiA1OCA0NiA0NiBRNjIgMzggNzAgNTIgUTc2IDY0IDYyIDY4IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iOCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PGNpcmNsZSBjeD0iNjIiIGN5PSI2OCIgcj0iOCIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg==">
  5. </picture>
  6. ### Give your AI agents memory that actually learns
  7. [![GitHub stars](https://img.shields.io/github/stars/alibaizhanov/mengram?style=social)](https://github.com/alibaizhanov/mengram/stargazers)
  8. [![PyPI](https://img.shields.io/pypi/v/mengram-ai)](https://pypi.org/project/mengram-ai/)
  9. [![npm](https://img.shields.io/npm/v/mengram-ai)](https://www.npmjs.com/package/mengram-ai)
  10. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  11. [![PyPI Downloads](https://img.shields.io/pypi/dm/mengram-ai)](https://pypi.org/project/mengram-ai/)
  12. [![Last commit](https://img.shields.io/github/last-commit/alibaizhanov/mengram)](https://github.com/alibaizhanov/mengram/commits/main)
  13. **[Website](https://mengram.io)** · **[Get API Key](https://mengram.io/#signup)** · **[Docs](https://mengram.io/docs)** · **[Console](https://mengram.io/dashboard)** · **[Examples](examples/)**
  14. </div>
  15. ```bash
  16. pip install mengram-ai # the CLI; JS SDK: npm install mengram-ai
  17. mengram try # see what memory would know about you — local only,
  18. # no account, nothing leaves your machine
  19. ```
  20. ```python
  21. from mengram import Mengram
  22. m = Mengram(api_key="om-...") # Free key → mengram.io
  23. m.add([{"role": "user", "content": "I use Python and deploy to Railway"}])
  24. m.search("tech stack") # → facts
  25. m.ask("what's my tech stack?") # → synthesized answer + citations
  26. m.episodes(query="deployment") # → events
  27. m.procedures(query="deploy") # → workflows that evolve from failures
  28. ```
  29. Native multilingual: ask in Russian, Chinese, Spanish, Japanese — Mengram retrieves and answers across 23 languages (Cohere multilingual embeddings + rerank).
  30. ---
  31. ## Install in one prompt (any AI tool)
  32. Paste 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.**
  33. ```
  34. Install Mengram for me. Fetch the canonical install guide at
  35. https://mengram.io/agent-install.txt and follow it precisely.
  36. My email is YOUR_EMAIL_HERE.
  37. ```
  38. Works 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.
  39. ---
  40. ## Claude Code — Memory That Survives /clear AND Auto-Compaction
  41. 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.
  42. ```bash
  43. # 1. Get a free key at https://mengram.io and save it once
  44. mkdir -p ~/.mengram && echo '{"api_key": "om-your-key-here"}' > ~/.mengram/config.json
  45. # 2. Install the plugin (hooks + MCP server + skill)
  46. claude plugin marketplace add alibaizhanov/mengram
  47. claude plugin install mengram@mengram
  48. # 3. Skip the cold start — import your existing session history
  49. # (secrets are redacted on your machine before anything is uploaded)
  50. mengram import claude-code
  51. ```
  52. What happens:
  53. ```
  54. Session Start → Loads your cognitive profile (fires after /clear, compaction, and restarts)
  55. Every Prompt → Searches past sessions for relevant context (auto-recall)
  56. After Response → Saves new knowledge in background (auto-save)
  57. Before a Bash → If the command matches a learned workflow with a weak record, asks you first (policy gate, CLI hooks)
  58. Before compact → Writes the working state down — last prompts, files edited, last commands, where Claude left off (CLI hooks)
  59. After compact → Puts that state back, verbatim, next to the host's summary — and tells you so in one line
  60. ```
  61. No manual saves. No tool calls. Claude just knows what you worked on yesterday — even after compaction ate the transcript.
  62. Prefer CLI-managed hooks instead of the plugin? `pip install mengram-ai && mengram setup` does the same via `mengram hook install`.
  63. ### Same memory in Codex and Cursor
  64. Codex and Cursor fire the same lifecycle events, so the same hooks run there — one memory across all three. `mengram setup` finds them on your machine and installs their hooks; or add them one by one:
  65. ```bash
  66. mengram hook install --codex # ~/.codex/hooks.json: session context, recall on every prompt, compaction checkpoint, auto-save + task card
  67. mengram hook install --cursor # ~/.cursor/hooks.json: session context, compaction checkpoint (back on the next tool call), auto-save
  68. ```
  69. Cursor has no per-prompt context hook (`beforeSubmitPrompt` can only allow or block), so mid-conversation recall there is on request via the MCP tools; session start and compaction are automatic.
  70. Every fact remembers which tool wrote it and when, and recall shows it: `deploys to Fly.io from main (codex, 2026-09-15)`. Each hook also tells the server which OS and tool it runs under, so a workspace path recorded on your Mac never reaches a Claude Code session on a Linux box, and a Cursor settings fact never reaches Codex — those are left out and counted (`facts_left_out_for_host`).
  71. ### Pick a task up where it was left — `mengram resume`
  72. When an agent stops, the hooks write a task card for the repository and branch: files touched, last commands, the last test run and the commit it ran on, plus the agent's draft of the task, what is done and what remains. The next session on that branch — tomorrow, another agent in another worktree of it, another machine — gets it first, and is told when the code has moved since the last check. A session on a branch with no card of its own (a fresh Orca worktree, say) is only told that cards exist, since another branch's card is usually another agent's task; `mengram resume` shows it on request:
  73. ```
  74. $ mengram resume
  75. [Mengram resume — where this task stands (2 h ago, from claude-code, branch main)]
  76. Task (agent draft, not confirmed): prepare the Dify example for publication
  77. Done:
  78. - three workflows assembled
  79. - save/recall round-trip checked through the API
  80. Remaining:
  81. - import the workflows into Dify and check the model's answers
  82. Last check: `python3 -m pytest -q tests/test_dify.py` → 4 passed in 0.31s
  83. The last check ran on 57cdde9; HEAD is now a1b2c3d (4 commits later). Its result describes the earlier state.
  84. Files touched: examples/dify-support/workflow.yml
  85. Sources: session 5d274778 · commit 57cdde9
  86. ```
  87. `mengram resume --open` serves a local page to correct the card, confirm it (confirmed text is never redrafted), pick another task or copy the context for a new session. The card lives in `~/.mengram/resume/` and needs no account; only the draft of task/done/remaining uses a model.
  88. ### No account? Keep the memory in a folder
  89. ```bash
  90. pip install mengram-ai
  91. mengram local init ./memory --provider anthropic --api-key sk-ant-... # or openai / ollama
  92. mengram import claude-code --memory ./memory # seed it from your Claude Code sessions
  93. mengram local map --memory ./memory --open # one page: who you are, what happened, what it learned
  94. mengram hook install --memory ./memory # the same four hooks, all local
  95. mengram server --memory ./memory # MCP for Claude Desktop, Cursor, any client
  96. ```
  97. The 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).
  98. Local search matches words in Unicode text, including Russian; it does not use embeddings or translate queries. Multiple Mengram sessions coordinate writes with a folder lock and merge independent additions. Conflicting edits require a reload instead of overwriting another session. Each changed file is replaced atomically, but the whole folder is not a single crash-atomic transaction, and external editors do not participate in the lock.
  99. ---
  100. ## Why Mengram?
  101. Every AI memory tool stores facts. Mengram stores **3 types of memory** — and procedures **evolve when they fail**.
  102. | | Mengram | claude-mem | Mem0 | Zep | Letta |
  103. |---|:---:|:---:|:---:|:---:|:---:|
  104. | Semantic memory (facts, preferences) | **Yes** | Yes | Yes | Yes | Yes |
  105. | **Episodic memory (events, decisions)** | **Yes** | Partial | No | No | Partial |
  106. | **Procedural memory (workflows)** | **Yes** | No | No | No | No |
  107. | **Procedures evolve from failures** | **Yes** | No | No | No | No |
  108. | **Cognitive Profile** | **Yes** | No | No | No | No |
  109. | **Native multilingual retrieval (23 languages)** | **Yes** | Partial | No | No | No |
  110. | **Ask & Citations (synthesized answer)** | **Yes** | No | No | No | No |
  111. | Multi-user isolation | **Yes** | No | Yes | Yes | No |
  112. | Knowledge graph | **Yes** | No | Yes | Yes | Yes |
  113. | Claude Code hooks (auto-save/recall) | **Yes** | **Yes** | No | No | No |
  114. | MCP server | **Yes** | Yes | Yes | Yes | Yes |
  115. | LangChain + CrewAI integrations | **Yes** | No | Partial | Partial | Partial |
  116. | **Import Claude Code history / ChatGPT / Obsidian** | **Yes** | No | No | No | No |
  117. | Pricing | **Free tier** | Free OSS (+cloud backup) | $19-249/mo | Enterprise | Self-host |
  118. ## Get Started in 30 Seconds
  119. **1. Install**
  120. ```bash
  121. pip install mengram-ai
  122. ```
  123. **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
  124. ```bash
  125. mengram setup
  126. ```
  127. Or get a key manually at [mengram.io](https://mengram.io/#signup) and `export MENGRAM_API_KEY=om-...`
  128. **3. Use**
  129. ```python
  130. from mengram import Mengram
  131. m = Mengram(api_key="om-...")
  132. # Add a conversation — auto-extracts facts, events, and workflows
  133. m.add([
  134. {"role": "user", "content": "Deployed to Railway today. Build passed but forgot migrations — DB crashed. Fixed by adding a pre-deploy check."},
  135. ])
  136. # Search across all 3 memory types at once
  137. results = m.search_all("deployment issues")
  138. # → {semantic: [...], episodic: [...], procedural: [...]}
  139. ```
  140. <details>
  141. <summary><b>File Upload (PDF, DOCX, TXT, MD)</b></summary>
  142. ```python
  143. # Upload a PDF — auto-extracts memories using vision AI
  144. result = m.add_file("meeting-notes.pdf")
  145. # → {"status": "accepted", "job_id": "job-...", "page_count": 12}
  146. # Poll for completion
  147. m.job_status(result["job_id"])
  148. ```
  149. ```javascript
  150. // Node.js — pass a file path
  151. await m.addFile('./report.pdf');
  152. // Browser — pass a File object from <input type="file">
  153. await m.addFile(fileInput.files[0]);
  154. ```
  155. ```bash
  156. # REST API
  157. curl -X POST https://mengram.io/v1/add_file \
  158. -H "Authorization: Bearer om-..." \
  159. -F "file=@meeting-notes.pdf" \
  160. -F "user_id=default"
  161. ```
  162. </details>
  163. <details>
  164. <summary><b>JavaScript / TypeScript</b></summary>
  165. ```bash
  166. npm install mengram-ai
  167. ```
  168. ```javascript
  169. const { MengramClient } = require('mengram-ai');
  170. const m = new MengramClient('om-...');
  171. await m.add([{ role: 'user', content: 'Fixed OOM by adding Redis cache layer' }]);
  172. const results = await m.searchAll('database issues');
  173. // → { semantic: [...], episodic: [...], procedural: [...] }
  174. ```
  175. </details>
  176. <details>
  177. <summary><b>REST API (curl)</b></summary>
  178. ```bash
  179. # Add memory
  180. curl -X POST https://mengram.io/v1/add \
  181. -H "Authorization: Bearer om-..." \
  182. -H "Content-Type: application/json" \
  183. -d '{"messages": [{"role": "user", "content": "I prefer dark mode and vim keybindings"}]}'
  184. # Search all 3 types
  185. curl -X POST https://mengram.io/v1/search/all \
  186. -H "Authorization: Bearer om-..." \
  187. -d '{"query": "user preferences"}'
  188. ```
  189. </details>
  190. ## 3 Memory Types
  191. ### Semantic — facts, preferences, knowledge
  192. ```python
  193. m.search("tech stack")
  194. # → ["Uses Python 3.12", "Deploys to Railway", "PostgreSQL with pgvector"]
  195. ```
  196. ### Episodic — events, decisions, outcomes
  197. ```python
  198. m.episodes(query="deployment")
  199. # → [{summary: "DB crashed due to missing migrations", outcome: "resolved", date: "2025-05-12"}]
  200. ```
  201. ### Procedural — workflows that evolve
  202. ```
  203. Week 1: "Deploy" → build → push → deploy
  204. ↓ FAILURE: forgot migrations
  205. Week 2: "Deploy" v2 → build → run migrations → push → deploy
  206. ↓ FAILURE: OOM
  207. Week 3: "Deploy" v3 → build → run migrations → check memory → push → deploy ✅
  208. ```
  209. This happens **automatically** when you report failures:
  210. ```python
  211. m.procedure_feedback(proc_id, success=False,
  212. context="OOM error on step 3", failed_at_step=3)
  213. # → Procedure evolves to v3 with new step added
  214. ```
  215. 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:
  216. ```json
  217. {
  218. "version": 3,
  219. "violated_assumption": "the build container had enough memory for a full build",
  220. "preconditions": ["check available memory before building"],
  221. "success_count": 11, "fail_count": 2
  222. }
  223. ```
  224. An agent loading v3 doesn't repeat the two mistakes that produced it — and knows what to verify before trusting the workflow.
  225. Or **fully automatic** — just add conversations and Mengram detects failures and evolves procedures:
  226. ```python
  227. m.add([{"role": "user", "content": "Deploy failed again — OOM on the build step"}])
  228. # → Episode created → linked to "Deploy" procedure → failure detected → v3 created
  229. ```
  230. ## Ask Your Memory (RAG built-in)
  231. `m.ask()` returns a synthesized answer with citations — not a raw fact list.
  232. Mengram embeds your query, retrieves the top relevant facts, and uses
  233. Cohere Chat to write a grounded answer with native source attribution.
  234. ```python
  235. result = m.ask("what programming languages do I use?")
  236. print(result["answer"])
  237. # 'You use Python and Rust. Python is your daily language [1] and
  238. # Rust is your favorite [2]. You also know Java for enterprise
  239. # systems [3].'
  240. for cit in result["citations"]:
  241. print(f' "{cit["text"]}" → {cit["sources"][0]["fact"]}')
  242. # "Python and Rust" → uses Python daily for backend development
  243. # "favorite [2]" → Rust is favorite language
  244. # "Java" → specializes in Java/Spring Boot
  245. ```
  246. 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).
  247. ## Cognitive Profile
  248. One API call generates a system prompt from all memories:
  249. ```python
  250. profile = m.get_profile()
  251. # → "You are talking to Ali, a developer in Almaty. Uses Python, PostgreSQL,
  252. # and Railway. Recently debugged pgvector deployment. Prefers direct
  253. # communication and practical next steps."
  254. ```
  255. Insert into any LLM's system prompt for instant personalization.
  256. ## Import Existing Data
  257. Kill the cold-start problem:
  258. ```bash
  259. mengram import chatgpt ~/Downloads/chatgpt-export.zip --cloud # ChatGPT history
  260. mengram import obsidian ~/Documents/MyVault --cloud # Obsidian vault
  261. mengram import files notes/*.md --cloud # Any text/markdown
  262. ```
  263. ## Integrations
  264. <table>
  265. <tr>
  266. <td width="50%">
  267. **Claude Code** — Auto-memory hooks
  268. ```bash
  269. mengram hook install
  270. ```
  271. 5 hooks: profile on start, recall on every prompt, save after responses, a policy gate before workflow-shaped Bash commands, and the outcome of each step written back after it runs.
  272. **The receipt.** Memory that works is invisible, so each hook leaves a line behind and the next session opens with the sum: *"Mengram, last session: recalled memories on 4 prompts · asked before 1 workflow with a weak record · recorded 3 step outcomes (2 ok, 1 failed)"*. Silent when nothing happened. `mengram receipt` shows the last session and the past 7 days.
  273. **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.
  274. [Docs](https://mengram.io/docs/claude-code)
  275. </td>
  276. <td width="50%">
  277. **MCP Server** — Claude Desktop, Cursor, Codex, Windsurf, Cline
  278. ```json
  279. {
  280. "mcpServers": {
  281. "mengram": {
  282. "command": "mengram",
  283. "args": ["server", "--cloud"],
  284. "env": { "MENGRAM_API_KEY": "om-..." }
  285. }
  286. }
  287. }
  288. ```
  289. 30 tools for memory management.
  290. </td>
  291. </tr>
  292. <tr>
  293. <td width="50%">
  294. **LangChain** — `pip install langchain-mengram`
  295. ```python
  296. from langchain_mengram import (
  297. MengramRetriever,
  298. MengramChatMessageHistory,
  299. )
  300. retriever = MengramRetriever(api_key="om-...")
  301. docs = retriever.invoke("deployment issues")
  302. ```
  303. </td>
  304. <td width="50%">
  305. **CrewAI**
  306. ```python
  307. from integrations.crewai import create_mengram_tools
  308. tools = create_mengram_tools(api_key="om-...")
  309. # → 5 tools: search, remember, profile,
  310. # save_workflow, workflow_feedback
  311. agent = Agent(role="Support", tools=tools)
  312. ```
  313. </td>
  314. </tr>
  315. <tr>
  316. <td width="50%">
  317. **OpenClaw**
  318. ```bash
  319. openclaw plugins install openclaw-mengram
  320. ```
  321. Auto-recall before every turn, auto-capture after. 12 tools, slash commands, Graph RAG.
  322. [GitHub](https://github.com/alibaizhanov/openclaw-mengram) · [npm](https://www.npmjs.com/package/openclaw-mengram)
  323. </td>
  324. <td width="50%">
  325. **CLI** — Full command-line interface
  326. ```bash
  327. mengram hook install # auto-recall + auto-save in Claude Code
  328. mengram import chatgpt export.zip --cloud # bring your ChatGPT history
  329. mengram rules --format claude_md # CLAUDE.md from what memory knows
  330. mengram local search "deployment" # search a local memory folder
  331. ```
  332. [Docs](https://mengram.io/docs/cli)
  333. </td>
  334. </tr>
  335. <tr>
  336. <td width="50%">
  337. **Claude Managed Agents** — MCP memory for hosted agents
  338. ```json
  339. {
  340. "mcp_servers": [{
  341. "type": "url",
  342. "name": "mengram",
  343. "url": "https://mengram.io/mcp/sse"
  344. }]
  345. }
  346. ```
  347. 30 memory tools via MCP. [Docs](https://mengram.io/docs/managed-agents)
  348. </td>
  349. <td width="50%">
  350. **n8n** — HTTP nodes for any workflow
  351. ```
  352. POST https://mengram.io/v1/add
  353. POST https://mengram.io/v1/search
  354. ```
  355. No code needed — drag and drop memory into any n8n workflow.
  356. [Docs](https://mengram.io/docs/n8n)
  357. </td>
  358. </tr>
  359. </table>
  360. ## Multi-User Isolation
  361. One API key, many users — each sees only their own data:
  362. ```python
  363. m.add([...], user_id="alice")
  364. m.add([...], user_id="bob")
  365. m.search_all("preferences", user_id="alice") # Only Alice's memories
  366. m.get_profile(user_id="alice") # Alice's cognitive profile
  367. ```
  368. ## Async Client
  369. Non-blocking Python client built on httpx:
  370. ```python
  371. from mengram import AsyncMengram
  372. async with AsyncMengram() as m:
  373. await m.add([{"role": "user", "content": "I use async/await"}])
  374. results = await m.search("async")
  375. profile = await m.get_profile()
  376. ```
  377. Install with `pip install mengram-ai[async]`.
  378. ## Metadata Filters
  379. Filter search results by metadata:
  380. ```python
  381. results = m.search("config", filters={"agent_id": "support-bot", "app_id": "prod"})
  382. ```
  383. ## Webhooks
  384. Get notified when memories change:
  385. ```python
  386. m.create_webhook(
  387. url="https://your-app.com/hook",
  388. event_types=["memory_add", "memory_update"],
  389. )
  390. ```
  391. ## Agent Templates
  392. Clone, set API key, run in 5 minutes:
  393. | Template | Stack | What it shows |
  394. |---|---|---|
  395. | **[DevOps Agent](examples/devops-agent/)** | Python SDK | Procedures that evolve from deployment failures |
  396. | **[Customer Support](examples/customer-support-agent/)** | CrewAI | Agent with 5 memory tools, remembers returning customers |
  397. | **[Personal Assistant](examples/personal-assistant/)** | LangChain | Cognitive profile + auto-saving chat history |
  398. ```bash
  399. cd examples/devops-agent && pip install -r requirements.txt
  400. export MENGRAM_API_KEY=om-...
  401. python main.py
  402. ```
  403. ## Use with AI Agents
  404. 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.
  405. ```python
  406. from mengram import Mengram
  407. m = Mengram(api_key="om-...")
  408. # Agent completes a task → store what happened
  409. m.add([
  410. {"role": "user", "content": "Apply to Acme Corp on Greenhouse"},
  411. {"role": "assistant", "content": "Applied successfully. Had to use React Select workaround for dropdowns."},
  412. ])
  413. # → Extracts: fact ("applied to Acme Corp"), episode ("Greenhouse application"),
  414. # procedure ("React Select dropdown workaround")
  415. # Next run → agent recalls what worked before
  416. context = m.search_all("Greenhouse application tips")
  417. # → Returns past procedures, failures, and successful strategies
  418. # Report outcome → procedures evolve
  419. m.procedure_feedback(proc_id, success=False,
  420. context="Dropdown fix stopped working")
  421. # → Procedure auto-evolves to a new version
  422. ```
  423. Works with any agent framework — CrewAI, LangChain, AutoGPT, custom loops. The agent just calls `add()` after actions and `search()` before decisions.
  424. ## Self-Hosted (Ollama)
  425. 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.
  426. | Model | Parameters | Works? |
  427. |-------|-----------|--------|
  428. | `llama3.1:8b` | 8B | Yes |
  429. | `mistral:7b` | 7B | Yes |
  430. | `gemma2:9b` | 9B | Yes |
  431. | `llama3.1:70b` | 70B | Best |
  432. | `phi4-mini:3.8b` | 3.8B | No — context too small |
  433. ## API Reference
  434. | Endpoint | Description |
  435. |---|---|
  436. | `POST /v1/add` | Add memories (auto-extracts all 3 types) |
  437. | `POST /v1/add_text` | Add memories from plain text |
  438. | `POST /v1/add_file` | Upload file (PDF, DOCX, TXT, MD) — vision AI extraction |
  439. | `POST /v1/search` | Semantic search |
  440. | `POST /v1/search/all` | Unified search (semantic + episodic + procedural) |
  441. | `GET /v1/episodes/search` | Search events and decisions |
  442. | `GET /v1/procedures/search` | Search workflows |
  443. | `PATCH /v1/procedures/{id}/feedback` | Report outcome — triggers evolution |
  444. | `GET /v1/procedures/{id}/history` | Version history + evolution log |
  445. | `GET /v1/profile` | Cognitive Profile |
  446. | `GET /v1/triggers` | Smart Triggers (reminders, contradictions, patterns) |
  447. | `POST /v1/agents/run` | Memory agents (Curator, Connector, Digest) |
  448. | `GET /v1/me` | Account info |
  449. Full interactive docs: **[mengram.io/docs](https://mengram.io/docs)**
  450. ### Quota Headers
  451. Every authenticated response includes usage headers:
  452. | Header | Description |
  453. |--------|-------------|
  454. | `X-Quota-Add-Used` | Add calls used this month |
  455. | `X-Quota-Add-Limit` | Add calls allowed this month |
  456. | `X-Quota-Search-Used` | Search calls used this month |
  457. | `X-Quota-Search-Limit` | Search calls allowed this month |
  458. SDKs expose this via `.quota`:
  459. ```python
  460. m.search("test")
  461. print(m.quota) # {"add": {"used": 5, "limit": 30}, "search": {"used": 12, "limit": 100}}
  462. ```
  463. ## Community
  464. - **[GitHub Issues](https://github.com/alibaizhanov/mengram/issues)** — bug reports, feature requests
  465. - **[GitHub Discussions](https://github.com/alibaizhanov/mengram/discussions)** — show your use case, ask questions
  466. - **[API Docs](https://mengram.io/docs)** — interactive Swagger UI
  467. - **[Examples](examples/)** — ready-to-run agent templates
  468. ## Star History
  469. <a href="https://star-history.com/#alibaizhanov/mengram&Date">
  470. <picture>
  471. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=alibaizhanov/mengram&type=Date&theme=dark" />
  472. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=alibaizhanov/mengram&type=Date" />
  473. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=alibaizhanov/mengram&type=Date" />
  474. </picture>
  475. </a>
  476. ## License
  477. Apache 2.0 — free for commercial use.
  478. ---
  479. <div align="center">
  480. **[Get your free API key](https://mengram.io/#signup)** · Built by **[Ali Baizhanov](https://github.com/alibaizhanov)** · **[mengram.io](https://mengram.io)**
  481. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.