GitHub - rcarmo/memento: a cross-agent memory system

5 min read Original article ↗

Memento

I wrote Memento to let several piclaw instances share facts without sharing their chats, reminders, credentials or machine-specific notes. One looks after personal work, another deals with servers, and project agents come and go; they all need to know things like where a service runs, why one system replaced another and which machine a project depends on.

Memento gives them an authenticated MCP service over a repository of Markdown concepts. Agents can search, follow links, read a concept and propose changes. Curators can review those proposals and publish them to Git.

Personal agent --\
Server agent -----+-- authenticated MCP --> Memento --> Markdown in Git
Project agent ---/                          |          operation journal
                                             `-------- search and graph indexes

Concepts have stable IDs, structured metadata and ordinary Markdown links. Read them with a text editor, inspect their history with Git or rebuild the indexes from the checkout. control.sqlite keeps operations, proposals, dynamic principals, credential verifiers and access activity; derived.sqlite holds FTS5, backlinks, graph metrics and optional embeddings.

What Belongs Here

Shared memory is for facts that should outlive a conversation and be useful to more than one agent:

  • where a service runs and who owns it;
  • why one system replaced another;
  • relationships between people, projects, machines and services;
  • aliases, tags and links that make the same fact easier to find later;
  • reviewed operating knowledge that several agents should follow.

Chat transcripts, daily notes, reminders, schedules, passwords and tokens stay with the agent or machine that owns them.

Using It

The common read path is short:

search -> read -> follow links if needed

The compact MCP surface exposes those frequent operations and keeps less common schemas in memory://catalog and memory://workflow/{goal}. memory_execute can chain known operations using saved results, such as searching for a project and reading the first match.

Writes normally go through review:

search -> read -> propose -> review -> apply -> Git commit -> index update

Memento checks the caller's namespace, the expected repository revision and the request's idempotency key. A retry returns the recorded result instead of creating another commit. Curators can also create, patch and rename concepts directly when those tools are exposed. Memento has no client-facing hard delete.

Administrators manage principals through the preset-driven /admin UI or role-filtered access_* tools on the same /mcp endpoint. Ordinary principals cannot discover or invoke those tools. New and rotated credentials are shown once; only verifiers are retained.

The complete tool contracts, roles, limits and response envelopes are in docs/contracts.md.

Search, Links And Local Models

FTS5 handles exact and lexical search. Markdown links supply backlinks and graph neighbourhoods. Neither needs a model.

GTE-small can add semantic ranking when different wording describes the same subject. Embeddings live in the derived database and can be regenerated from Markdown. On memory-constrained hosts, Memento runs GTE in short-lived batches and releases the process afterwards.

A fine-tuned 26M-parameter Needle model can route a small set of natural-language read requests. It emits a candidate action that Memento validates before running. Other configured model slots may produce cited answers or draft proposals and maintenance suggestions.

Model setup and measurements live in docs/semantic-search.md, docs/needle-fine-tuning.md and docs/needle-performance.md.

Assets And Skills

A concept can carry an immutable versioned asset pack in Git LFS. The Markdown remains searchable while diagrams, templates, datasets or a complete agent skill travel in an attached ZIP. Large ZIPs can be sent as raw binary to the authenticated staging endpoint and referenced from an ordinary proposal, avoiding base64 expansion in MCP JSON.

Skill concepts live under /skills/, carry the skill tag and match the SKILL.md inside their pack. memory_asset_get returns a selected version and its manifest; memento-skill-import validates it again before placing it in a workspace. Memento does not install or execute recalled skills on behalf of a client.

The repository also ships an Agent Skills package at .agents/skills/memento/SKILL.md. It gives Pi, Piclaw and Codex agents a compact workflow for search, reads, proposals, curation, namespaces, assets and retry reconciliation.

Visual Debugging

The optional /graph surface helps humans inspect how memories are being created and managed. It shows explicit links, provenance, sizes, assets, proposals, index state and a separately labelled semantic overlay in a 2.5D scene.

Memento visual debugger showing linked memories and the selected-memory inspector

The debugger is disabled by default and unauthenticated when enabled. It is meant for a trusted development network, not an Internet-facing service. ADR 0011 and docs/graph-explorer-plan.md describe the boundary and delivery plan.

Running It

Memento supports Python 3.12-3.14 and ships as a non-root multi-architecture container. Start with examples/config.v1.json, set MEMENTO_ADMIN_MASTER_KEY, then use docs/operations.md for deployment, health checks, backup and recovery. docs/access-management.md covers bootstrap, /admin, MCP access tools, one-time credentials and explicit container master-key rotation.

For development:

make install-dev
make check

Tagged images are published at ghcr.io/rcarmo/memento. The DiskStation profile, including the scalar Intel J3455 path, is in docs/diskstation.md.

Client setup guides cover Pi, Piclaw and Codex.

Documentation

Credits

rcarmo/umcp supplies the MCP server, Streamable HTTP transport and request context. Memento's Rust semantic-search runtime was validated against rcarmo/go-gte, using the thenlper/gte-small weights. The shallow router is fine-tuned from cactus-compute/needle.

Memento is MIT licensed. Third-party models, code and vendored browser libraries are listed in docs/attribution.md.