Skip to main content
Glama
README.md
# Membot

**A portable memory store that agents and people read through the same tools, with attribution on every write, and no LLM in the retrieval path.**

Membot is an [MCP](https://modelcontextprotocol.io/) server. Point an agent at it and the agent
gets a searchable store it can read, annotate and extend. Point a person at the same store
through [Vector+ Studio](https://github.com/project-you-apps/vector-plus-studio) and they see the
same records, the same notes, and the same history.

A **cartridge** — a cart — is one file. It holds passages, their embeddings, and a compact binary
signature per passage. You can copy it, back it up, hand it to someone, or keep it on a machine
that never touches the internet. Carts are built either by drag-and-drop in the Vector+ Studio
front end, or with the Desktop Builder for large local builds and OCR. Both ingest your
documents and embed them locally; building a cart does not send anything anywhere.

---

## Why this instead of a vector database

**Retrieval costs no tokens.** Search is a sentence-transformer embedding plus binary matching
plus keyword reranking. No model is called to answer a query. For an agent making hundreds of
retrievals in a run, that is the difference between a background cost and a line item.

**It stores WHY, which almost nothing does.** Every record system stores who touched what and
when. Almost none store **why**, because why has to be captured **at the moment of the decision
and cannot be reconstructed afterward.** Six months on, the document is still in the folder and
the person who chose it has moved on. Membot has a field for the part that leaves with them.

**Your reasoning is yours until you publish it.** A note is born **private**. Nothing else can
see it until you explicitly share it, because a shared "why" that is on by default is
surveillance rather than memory. ⇒ People write honestly only when they are not performing.

**Every write carries who, where and when.** Not an audit log bolted beside the data but an
invariant in the format. A note written through a web browser and a note written by an agent at
3am are both attributed, and both say which surface they came from.

**Corrections never erase.** When a note is corrected, the old one is marked superseded and
**stays** -- rendered struck through, still attributed. Nothing in the normal path removes a
record. A reader can see that someone was wrong, who said so, and when.

**It is a file.** No cluster, no managed service, no egress. The store is portable by
construction, which matters when the data is not allowed to leave a building.

---

## Quick start

### Prerequisites

- Python 3.10+
- An MCP-compatible client — [Claude Code](https://claude.com/claude-code), Claude Desktop,
  [OpenClaw](https://github.com/anthropics/openclaw), or your own harness

### Install

```bash
git clone https://github.com/project-you-apps/membot.git
cd membot
pip install -r requirements.txt
```

### Run

```bash
# Local (stdio) — for agents that launch Membot as a subprocess.
# Read-only by default; add --writable to enable stores and saves.
python membot_server.py

# Remote (HTTP) — for any MCP client over the network.
python membot_server.py --transport http --port 8000

# Writable, for a personal or team server.
python membot_server.py --transport http --port 8000 --writable
```

| Flag | Default | Description |
| --- | --- | --- |
| `--transport` | `stdio` | `stdio`, `http`, or `sse` |
| `--host` | `127.0.0.1` | Bind address (HTTP/SSE) — **loopback only by default.** ⛔ `0.0.0.0` accepts connections from anything that can route to the box, and the API key does not cover every route |
| `--port` | `8000` | Listen port (HTTP/SSE) |
| `--writable` | off | Enables `memory_store` and `save_cartridge` |

**stdio** is JSON-RPC over stdin/stdout. **HTTP** serves Streamable HTTP at
`http://{host}:{port}/mcp`.

> ⚠ **Read [Security posture](#security-posture) before exposing an HTTP server to anything but
> loopback.** The API key and rate limit do not cover every route.

### If HTTPS fails but your browser works

A first search, build, sign-in or mount failing with `CERTIFICATE_VERIFY_FAILED` — while a
browser on the same machine reaches the same address fine — means the machine is **intercepting
TLS**. Consumer antivirus and corporate proxies do this by presenting their own certificate.
Browsers accept it because they verify against the OS trust store; Python verifies against a
bundled CA set that has never heard of it.

`requirements.txt` includes [`truststore`](https://pypi.org/project/truststore/), which routes
verification through the OS store. **Verification stays fully on** — this changes where trust
comes from, not whether it is checked.

⚠ Watch for it when a mount returns **503**: a TLS failure inside an access check is
indistinguishable from a permissions outage, and the error will not mention certificates.
Full diagnosis: [docs/TROUBLESHOOTING-TLS-INTERCEPTION.md](../docs/TROUBLESHOOTING-TLS-INTERCEPTION.md)

---

## What you can do with it

Membot exposes about fifty MCP tools. Grouped by the job rather than alphabetically:

| Job | Tools |
| --- | --- |
| **Find things** | `memory_search` · `multi_search` · `walk_associate` · `get_passage` · `passage_links` |
| **Mount and manage carts** | `mount_cartridge` · `unmount` · `list_cartridges` · `multi_mount` · `multi_mount_directory` · `multi_list` · `multi_unmount` · `get_status` |
| **Annotate** | `note_add` · `notes` · `note_share` · `propose_correction` · `proposals` |
| **Write and persist** | `memory_store` · `save_cartridge` · `get_pattern_meta` |
| **Per-seat attention** | `seat_hot_stack` · `firm_hot_stack` · `seat_hide` · `seat_hidden` |
| **Scoped subsets** | `subcart_create` · `subcart_list` · `subcart_export` · `subcart_delete` |
| **Agent-owned memory (Mempack)** | `mempack_read_pattern_i` · `mempack_update_pattern_i` |
| **Shared writable carts (Membox)** | `membox_mount` · `membox_search` · `membox_imprint` · `membox_acquire_lock` · `membox_release_lock` · `membox_lock_holder` · `membox_list` · `membox_status` · `membox_unmount` |
| **Watch for change** | `watch` · `unwatch` · `what_changed` |
| **Federate across machines** | `federate_publish` · `federate_consolidate` · `federate_load` · `federate_migrate_jsonl` |

⭐ **For agents, there is a companion document:** [AGENTS.md](AGENTS.md) that describes which tool for which
job, what the returns mean, and the failure modes worth handling.

---

## How search works

Three signals, combined:

- **Cosine** over sentence-transformer embeddings (Nomic) — semantic similarity.
- **Hamming** over a 768-bit binary signature per passage (96 bytes) — fast, cheap prefiltering
  and a second opinion on ranking.
- **Keyword reranking** — surface matches that embedding geometry misses, like identifiers and
  proper nouns.

ⓘ **An honest note on "associative" search.** Membot can return neighbours a literal query would
not have found. Having tested it, we attribute that to the **embedding model's** representation
quality rather than to anything downstream of it. We no longer claim an architectural
differentiator in retrieval, and we would rather say so than have you discover it in a bake-off.

The repository includes an optional GPU engine under a separate licence. It is **not required**
and is not part of the retrieval path described above.

---

## Notes, attribution and history

The features customers actually asked for, in order of how often they ask:

**Notes on passages.** A note carries a `kind` — why, context, caution, decision, prediction,
recommendation — plus its author, surface and timestamp. Notes live beside the cart in a sidecar
file, not inside it, so annotating does not rewrite the data.

**Private by default, shared on purpose.** `note_add` creates a private note; `note_share` is a
separate, deliberate act. ⛔ There is no setting that makes new notes public. ⚠ And a correction
**cannot widen who can see the original** — correcting something must never leak it.

**Correction without erasure.** A correcting note supersedes its predecessor. The superseded note
renders **struck through**, still attributed. ⛔ Nothing in the normal path deletes a note.

**A hash-chained journal.** Every note event appends a line carrying the previous line's hash, so
an edited, reordered or interior-deleted entry is detectable. A **high-water mark** in a second
file closes trailing deletion, which the chain alone cannot catch.

⭐ **Keep the journal in a repo your reviewer also clones** and the last gap closes too: every
clone is an independent witness, so a rewrite is detectable by anyone holding one.

---

## The Hot Stack

A shared cart does not have *a* hot stack. Two people searching the same store build different
hierarchies over it, and both are correct. So Membot keeps attention per seat, and rolls it up
separately.

**`seat_hot_stack`** returns what **you** have been working on in the mounted cart, ranked by
your own attention. It scores only passages you have actually touched, so a passage another seat
has opened forty times is cold for you if you have never opened it. ⇒ Untouched material is
cold, not absent: a thing you could read but never have simply does not rise.

**`firm_hot_stack`** returns what the **organization** is warm on, which is a different question
and not the sum of the first one. ⭐ The signal that exists only here is **how many distinct
people touched a passage**. One person reading something forty times and forty people reading it
once produce the same access count and mean completely different things about a company.
⇒ Ranked by distinct seats, that difference becomes visible.

**`seat_hide` / `seat_hidden`** let a seat drop something out of its own view without removing it
for anyone else — the free rung of the delete ladder.

ⓘ **What this is and is not.** It is attention over a mounted cart, maintained per seat, and it
works today. ⛔ It is *not* yet a personal memory that follows you across carts: **promotion** —
moving what you worked on in a session into a durable personal or organizational store — is
designed and not built, and a personal cart is not auto-mounted when you sign in. ⇒ Both are on
the roadmap below.

---

## Security posture

Stated plainly, because the previous version of this file was wrong about it.

**What the API key covers.** `MEMBOT_API_KEY` and the 60 req/min rate limit are enforced in the
MCP protocol hook, which means they apply to **`/mcp` tool calls only**. ⛔ The server also serves
REST routes under `/api/*`, `/depot/*` and `/app` as ordinary HTTP endpoints — **those get
neither the key check nor the rate limit.** ⚠ The middleware reads `Authorization: Bearer <key>`
only; `X-API-Key` is ignored.

⇒ **Do not expose an HTTP Membot to an untrusted network.** If you need remote access, proxy
`/mcp` and block the rest.

**How identity works.** The seat is resolved rather than accepted:

- **stdio** — the claim is trusted. A local pipe *is* the user.
- **a verified token present** — the seat is derived from it, and a disagreeing claim is recorded
  as overridden.
- **no usable identity** — the claim is honored and recorded as `claimed`, except in namespaces
  the server reserves for itself.

⇒ Journal entries carry `identity_source: verified | claimed | default`. ⭐ **A reader should
treat `claimed` as present but unverified, never as equivalent to `verified`.** Binding a write
to an author cryptographically is designed and not built.

**Cartridges are data, and should be treated as data you trust.** Loading a cart from an
untrusted source is not currently a safe operation. ⚠ Hardening the loader so that admissibility
is checked before anything is materialized is in progress; until it lands, **only open carts you
or your organization produced.**

Further hardening is underway; this section will say more as it lands.

---

## Roadmap, stated as roadmap

| | state |
| --- | --- |
| Notes, correction-by-supersession, hash-chained journal | ✅ shipped |
| Per-seat hot stack and hidden set | ✅ shipped |
| Mempack — agent-owned writable carts | ✅ shipped |
| Membox — shared writable carts with a lock | ✅ phase 1 |
| Federation across machines | ✅ shipped |
| Hot Stack — per seat and firm-wide | ✅ shipped |
| **Promotion — session work into a durable personal store** | ⬜ designed |
| **Auto-mounted personal cart on sign-in** | ⬜ designed |
| **Verified identity binding (signatures)** | ⬜ designed |
| **Sealed carts — a one-way, append-only posture** | ⬜ designed |
| **Loader hardening** | ⬜ in progress |
| **Change notification to subscribers** | ⬜ designed |

---

## Related

- **[Vector+ Studio](https://github.com/project-you-apps/vector-plus-studio)** — the browser
  front end. Drag and drop to build a cart, search it, read and write the same notes.
- **[AGENTS.md](AGENTS.md)** — the agent-facing guide to these tools.

## Licence

| Component | Licence |
| --- | --- |
| Server, tools and utilities | **Business Source License 1.1** — see [LICENSE](LICENSE) |
| Optional GPU engine (`bin/*`) | Proprietary — see [bin/LICENSE](bin/LICENSE) |

**Non-production use is free and needs no agreement with us.** Read it, copy it, modify it,
redistribute it, run it internally, evaluate it, test it, demo it. ⇒ That is what the licence
calls non-production use, and it covers everything short of charging for it.

⚠ **Production use requires a commercial licence.** If Membot is part of a product or service you
charge for, or any revenue-generating application, [contact us](mailto:andy@project-you.app).
⭐ We would rather hear from you than not — the point of the licence is to start a conversation,
not to stop you evaluating.

ⓘ **It does not stay closed.** On the Change Date in [LICENSE](LICENSE), each version becomes
available under the MIT Licence. The licence applies per version, so each release carries its
own date.

⛔ **The GPU engine in `bin/` is not covered by the above** and is not part of the Licensed Work.
It is proprietary, it is optional, and it is not in the retrieval path.