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_inventory returns bounded metadata, body digests and asset summaries without concept bodies. The execute-only compare_manifest operation compares a caller-provided local manifest with one authorised namespace page; Memento treats local paths as opaque labels and never reads caller files. memory_execute can also 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 may review proposals they authored when they have write access to every affected path; author_principal and reviewed_by preserve that fact in the audit trail. Curators can also create, patch and rename concepts directly when those tools are exposed. Curators can also trash, restore or purge concepts. Trash preserves original namespace permissions; purge removes current content and assets with explicit confirmation, retaining Git history.

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.

Start with the documentation index, agent workflow diagrams or proposal review and refiling guide. The tool contracts define roles, arguments, limits and response envelopes.

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 persistent derived.sqlite: they remain rebuildable from Markdown, but routine container updates and derived rebuilds preserve reusable vectors. On memory-constrained hosts, progressive mode processes one missing or stale concept at a time in a short-lived, low-priority, single-threaded worker, pauses for recent requests or high sampled CPU use, and releases model RAM after each item.

A fine-tuned 26M-parameter Needle model can route a small set of natural-language read requests. Release builds pre-expand its weights into a read-only mapped FP32 sidecar, and each route runs in a short-lived Go worker so model pages remain reclaimable rather than resident in the daemon. It emits a candidate action that Memento validates before running. When configured, memory_answer assembles a versioned, authorisation-scoped evidence set before asking a model for a cited answer. Secret intent abstains before cache lookup, retrieval, repository reads, graph access or model invocation. Other optional model slots can draft proposals and maintenance suggestions; deployments without a configured provider keep the answer tool disabled.

Model setup and search behaviour are documented in docs/semantic-search.md; retained Needle training and performance results live under docs/evidence/needle/.

Assets And Skills

A concept can include an immutable versioned asset pack as an ordinary Git blob. The Markdown remains searchable while diagrams, templates, datasets or a complete agent skill travel in an attached ZIP. Packs that fit the configured MCP request ceiling use attach_asset_pack.zip_base64, keeping proposal creation inside MCP. Larger packs can use memory_asset_stage_begin/memory_asset_stage_status; the begin call returns a one-time raw-upload ticket so the upload command does not need the principal's bearer token.

Skill concepts live under /skills/, have the skill tag and match the ZIP-root SKILL.md byte-for-byte. Reviewers check the generated manifest and digest before approval; clients verify accepted bytes through memory_asset_get manifest, file and archive-range views. Large ZIPs are downloaded in chunks pinned to their version and digest. memento-skill-import-go validates a recalled pack 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, inventory, manifest comparison, 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 and index state in a 2.5D scene. Embedding similarity is a separately labelled, default-off layer: selected nodes reveal top semantic neighbours as amber segmented arcs with cosine/model metadata.

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, implemented API and deferred revision-playback work.

Running It

Memento ships as a non-root, pure-Go 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 the dedicated admin/curator profile split, Piclaw and Pi MCP configuration, /admin, direct MCP access tools, one-time credentials and explicit container master-key rotation.

The main branch is the verified pure-Go v1.0.0 implementation for ghcr.io/rcarmo/memento. It builds static amd64-v1 and arm64 binaries and a non-root distroless image:

python3 tools/prepare_runtime_models.py
make quality
make audit
make ui-setup # Add UI_INSTALL_FLAGS=--with-deps on a fresh Linux host
make ui-test UI_REPEAT=2
make performance
make model-test
make corpus-test
make release-check MEMENTO_VERSION=1.0.0 SOURCE_DATE_EPOCH=0
make go-container-contract MEMENTO_VERSION=1.0.0

The browser gate requires Node 22.23.1 and the locked Playwright dependencies. It runs against disposable local Go fixtures without production credentials or model files; browser test instructions cover setup, focused runs and failure artifacts.

memento-go is the native daemon and maintenance CLI. memento-embed-go handles framed GTE requests; memento-needle-go handles one mapped Needle route per process; memento-needle-model-go builds the deterministic FP32 sidecar; and memento-skill-import-go installs recalled skill packs. The image also exposes memento-embed as the compatibility name expected by existing configuration. It preserves /etc/memento/config.json, /var/lib/memento, /models, port 8000, /mcp, graph/admin routes, authentication and response contracts. Existing repository and SQLite formats are opened directly and remain readable by the previous 0.5.9 image for rollback. Python/Rust executables and libraries are not retained as runtime compatibility shims.

The DiskStation profile and its J3455 baseline constraints are in docs/diskstation.md.

Client setup guides cover Pi, Piclaw and Codex.

Documentation

The documentation index groups setup, agent tasks, contracts, operations and project records. Common starting points:

• Agent workflows -- discovery, comparison, execute plans, asset recall and interrupted writes.
• Proposals -- submission, review decisions, rejection, refiling, stale proposals and skill updates.
• Operations -- deployment, health, backup and recovery.
• System diagrams -- transport, storage, publication and model flows.

Credits

Memento's standalone Go uMCP module implements the protocol behaviour pinned from rcarmo/umcp. The pure-Go semantic runtime uses the thenlper/gte-small weights and retains algorithmic/fixture provenance from rcarmo/go-gte. 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.