memotrust

<div align="center"> <img src="assets/memotrust-icon.png" alt="memotrust" width="120" /> # memotrust ### Verified memory for AI agents. Your agents remember only what's **true**. [](https://www.npmjs.com/package/memotrust) [](LICENSE) [](https://modelcontextprotocol.io) [](https://github.com/Idanref/memotrust) Agents propose memories. **Evidence** verifies them. `recall()` returns only what has *earned* trust, so a hallucinated, stale, or **poisoned** "fact" never reaches your other agents. <br/> <img src="assets/demo/demo.gif" alt="An agent proposes memories; a poisoned one is caught at the gate while verified memory flows to every agent." width="780" /> </div> --- ## Why memotrust Give your agents a shared memory and it's a superpower, until one agent hallucinates a fact, copies a stale number, or reads a poisoned note. In every other memory layer, that mistake becomes **every agent's "truth"**, silently, forever. (Memory poisoning is OWASP agentic risk **ASI06**.) memotrust flips the default: **nothing is trusted on arrival.** A memory reaches `recall()` only after it's **verified against a real source** or **approved by a human**. Trust decays. Disputes withhold. Every verdict keeps a receipt. ## What's inside | | | |---|---| | <img src="assets/icons/feat/recall.png" width="20">&nbsp; **Trusted recall** | `recall()` returns only verified, fresh, in-scope memory, ranked. No guesses, no stale wins. | | <img src="assets/icons/feat/shared.png" width="20">&nbsp; **One shared memory** | Every agent, Claude Code, Cursor, any MCP client, reads and writes the same store. Git-backed, so what your agents know is versioned, diffable, and portable. | | <img src="assets/icons/feat/shield.png" width="20">&nbsp; **Poison can't spread** | Every new memory is quarantined until proven. One agent's bad note can't become another's fact. | | <img src="assets/icons/feat/verify.png" width="20">&nbsp; **MCP Verifiers** | Read-only checks that turn a claim into trusted knowledge: built in, or connected to a source of truth. | | <img src="assets/icons/feat/connect.png" width="20">&nbsp; **Read-only connectors** | Confirm domain claims against live data. **Mixpanel** built-in; connect any read-only MCP source. | | <img src="assets/icons/feat/dashboard.png" width="20">&nbsp; **Dashboard** | A local UI to review, approve, dispute, and manage every memory and every verifier connection. | | <img src="assets/icons/feat/receipt.png" width="20">&nbsp; **Receipts, not vibes** | Every verdict records the query, the reading, and the judgment. Audit *why* anything is trusted. | | <img src="assets/icons/feat/files.png" width="20">&nbsp; **Just files** | Markdown claims plus an append-only log, git-backed. Human-readable, diffable, no database. | ## One memory, every agent memotrust is the **shared source of truth** for your whole agent fleet. Claude Code, Cursor, and every MCP client read and write the *same* store, so a fact one agent proves, all of them can trust. And because it's **git-backed**, that memory is versioned, diffable, and portable: branch it, review it, roll it back, sync it however you sync code. It's the home for everything your agents know, and every line of it has earned its place. ## Quick start ```bash npx memotrust install # create the store, git-init it, register the MCP with your agent ``` Point **Claude Code**, **Cursor**, or any MCP client at it, and your agents can `propose` and `recall`. The dashboard comes up at **http://localhost:8765**. ## The dashboard Everything your agents know, and exactly how much of it is proven. Review the inbox, approve or dispute at a glance, watch trust coverage, and audit any claim's full evidence chain. <div align="center"> <img src="assets/dashboard.png" alt="memotrust dashboard: memories grouped by trust (verified, proposed, disproven, approved) with an inbox and live trust coverage." width="840" /> </div> ## MCP verifiers, read-only A verifier confirms or refutes a claim against a **source of truth**. It is **always read-only**: it can query, never write, update, or delete. - **Built in, zero credentials.** Check a claim against a file, a URL, or a command: ```yaml check: {"kind": "file", "path": "package.json", "contains": "pnpm"} check: {"kind": "url", "url": "https://api.example.com/health", "status": 200} ``` - **Connect a source of truth.** **Mixpanel** is built-in (a read-scoped service account confirms growth and metric claims). Connect any other read-only MCP data source, or let your agent submit a read-only observation, and **memotrust decides the verdict, the agent never can.** - **Human approval.** Anything you'd rather confirm yourself, in one click. <div align="center"> <img src="assets/dashboard-verifiers.png" alt="Verifiers page: read-only connectors (Mixpanel, Amplitude, PostHog, GitHub, Human approval) that turn proposed memories into trusted knowledge." width="840" /> </div> > `command` checks are **disabled by default**: a poisoned claim must never become code execution. Opt in with `MEMOTRUST_ALLOW_COMMAND_CHECKS=1`. ## How it works <div align="center"> <img src="assets/how-it-works.png" alt="Flow: an agent proposes a memory, it is quarantined, memotrust judges the evidence and records a receipt, and only trusted memory is recalled. A 60-day decay or a human dispute sends it back to withheld." width="900" /> </div> There is **no LLM inside the store**: your agent extracts durable facts and proposes them over MCP; memotrust only ever *judges* the evidence and records the receipt. ## The tools your agent gets | Tool | What it does | |---|---| | `recall` | Only trusted + fresh + in-scope memory; disproven approaches come back as **warnings** | | `propose` | File a new memory; it lands quarantined, never trusted on arrival | | `search` | Everything at any trust level, each result labeled with its status | | `vocabulary` | Existing spaces + tags, so agents reuse names instead of inventing synonyms | | `pending_verifications` | Claims that carry a machine-checkable assertion, awaiting a reading | | `submit_evidence` | Submit a read-only observation; memotrust judges, not the agent | ## memotrust vs. a plain memory layer | | plain memory | **memotrust** | |---|---|---| | New memory is… | trusted immediately | **quarantined until verified** | | Hallucinated / poisoned note | served to every agent | **withheld, never recalled** | | Stale facts | linger and win | **decay after 60 days, re-verify** | | "We already tried that" | forgotten | **returned as a warning** | | Why is this trusted? | ¯\\\_(ツ)\_/¯ | **an auditable receipt** | ## Contributing Issues and PRs welcome. `npm test` runs the store + verifier suite; `npm run test:e2e` runs the end-to-end MCP acceptance test. House style: [docs/code-style.md](docs/code-style.md). <div align="center"> **If verified memory is something your agents need, [⭐ star the repo](https://github.com/Idanref/memotrust). It helps a lot.** [MIT](LICENSE) · built for the [Model Context Protocol](https://modelcontextprotocol.io) </div>