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

[![npm](https://img.shields.io/npm/v/memotrust?color=6d6bf5&label=npm)](https://www.npmjs.com/package/memotrust)
[![license](https://img.shields.io/npm/l/memotrust?color=34d39a)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-9b7bff)](https://modelcontextprotocol.io)
[![stars](https://img.shields.io/github/stars/Idanref/memotrust?style=social)](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>