{"slug": "rcarmo-memento-a-cross-agent-memory-system", "title": "Rcarmo/memento: a cross-agent memory system", "summary": "Rui Carmo released Memento, a cross-agent memory system that stores shared facts for multiple AI agents on the same network, using Git-backed Markdown files and local models for retrieval. The system allows any MCP client to search, read, and propose changes, keeping durable knowledge separate from agent-specific context like conversations or credentials.", "body_md": "Memento is a memory system designed to be shared by multiple agents on the same network.\n\nAgents remember several kinds of things, and they should not all live in the same place. Conversations are short-lived context. Reminders belong to the agent that must deliver them. Credentials belong to one machine or user. Facts such as \"Smith runs Piclaw\", \"this service replaced that one\" or \"the backup lives here\" may need to last for years and be available to everyone.\n\nMemento stores those shared facts. I built it for several Piclaw instances, but any MCP client can connect, search, read, submit proposals and, with curator access, publish changes.\n\nTwo small local models help with retrieval. [ cactus-compute/needle](https://github.com/cactus-compute/needle) routes simple natural-language requests to read operations, while\n\n[and the](https://github.com/rcarmo/go-gte)\n\n`rcarmo/go-gte`\n\n[weights find related concepts when the wording differs. Permissions and Git changes stay in Memento.](https://huggingface.co/thenlper/gte-small)\n\n`thenlper/gte-small`\n\n``` php\nflowchart LR\n    request[Agent request] --> core[Memento]\n    core --> needle[Needle<br/>shallow routing]\n    core --> gte[GTE-small<br/>semantic ranking]\n    core --> models[Local models<br/>answers, proposals, Dream]\n    needle --> result[Checked result]\n    gte --> result\n    models --> result\n    result --> store[(Git knowledge<br/>and search indexes)]\n```\n\nNeedle maps a read request to search, status, read or graph operations, and gives up when it cannot classify one. GTE-small supplies vectors for semantic ranking. Other local models can write cited answers, draft proposals or suggest maintenance; access control and repository writes stay in Memento.\n\n- Markdown concepts with stable IDs, links and Git history.\n- Authenticated MCP search, read, proposals and role-based curation for any compatible agent.\n- Lexical and graph search, with optional local GTE semantic ranking.\n- Proposal-first, revision-checked and idempotent Git writes.\n- Versioned Git LFS asset packs, including complete recallable skills.\n- Local Needle routing, GTE embeddings and optional answer/proposal/Dream models.\n- Rebuildable indexes, crash recovery, backups, metrics and non-root deployment.\n\nTools, limits and roles are in [ docs/contracts.md](/rcarmo/memento/blob/main/docs/contracts.md); the storage and transaction design is in\n\n[.](/rcarmo/memento/blob/main/docs/implementation.md)\n\n`docs/implementation.md`\n\nI wrote Memento to keep my [ piclaw](https://github.com/rcarmo/piclaw) instances up to date and sharing knowledge without making them share everything else. One handles personal work, another looks after servers, and others come and go with projects; each has its own chats, notes, reminders, tools and credentials.\n\nCopying Markdown between them quickly creates several versions of the truth, but sharing their chat databases would mix private conversations and machine-specific state. Memento gives them one place for facts that should last, while everything local stays local.\n\nPiclaw is how I use it, but it is not a requirement. Any MCP client can use the same authenticated tools.\n\n```\nPersonal agent ──┐\nServer agent ────┼── authenticated MCP ──> Memento ──> shared Markdown knowledge\nProject agent ───┘                              ├──────> operation journal\n                                                └──────> search indexes\n```\n\n[ rcarmo/umcp](https://github.com/rcarmo/umcp) provides the MCP server and transport core used for search, reads and proposals. Clients never receive direct filesystem or Git access.\n\nMemento stores durable concepts: people, projects, machines, services, decisions and relationships that should outlive any one conversation. Each concept is an ordinary Markdown file with structured metadata, a stable ID and links to related concepts.\n\nExamples include:\n\n- where a service runs and who owns it;\n- why one system replaced another;\n- which project depends on a particular machine;\n- aliases, tags and links needed to find the same fact later;\n- reviewed operational knowledge that several agents should use consistently.\n\nConcepts are Markdown files in Git. You can read them with a text editor, copy them elsewhere, inspect their history with Git and rebuild the search indexes.\n\nMemento does not store:\n\n- chat transcripts and temporary conversation context;\n- an agent's private daily notes or local memory summaries;\n- reminders and scheduled jobs;\n- passwords, tokens, keychains or machine configuration.\n\nThose stay with the agent that owns them.\n\nAgents search for a topic and read the matching concept. They can also chain a few operations, such as finding a project and reading the first result.\n\nWrites begin as proposals. An agent drafts a change, a curator reviews it, and Memento checks permissions, paths and the current Git revision before committing anything. A model may suggest wording or relationships, but cannot publish them.\n\nGit owns knowledge;\n\n`control.sqlite`\n\nowns operations; search indexes can be rebuilt; models do not write.\n\nGit holds concepts and their history. Every accepted change produces a commit tied to the caller, operation and previous revision. Renames keep the same concept ID and update inbound links in the same transaction.\n\n`control.sqlite`\n\nrecords proposals, repeated-request protection, write journals, leases and scheduler state. FTS5, graph metadata and optional vectors live in a separate derived database that can be rebuilt from Markdown.\n\nThe default MCP surface covers discovery, search, read and short multi-step requests. Less common operations and their schemas are available through `memory://catalog`\n\nand `memory://workflow/{goal}`\n\ninstead of being placed in every agent prompt.\n\nPermissions are checked before search results are ranked or returned. `memory_execute`\n\ncan chain known operations with saved references, but cannot run a shell or open arbitrary files or network connections. Tool and role details are in [ docs/contracts.md](/rcarmo/memento/blob/main/docs/contracts.md).\n\nCross-instance writes are proposal-first:\n\n``` php\nsearch -> read -> propose -> review -> apply -> Git commit -> index update\n```\n\nA proposer can describe a change and inspect its diff. A curator reviews and applies it against the expected repository revision. Stale writes conflict instead of replacing newer knowledge, and a retried request returns the recorded result rather than making a second commit.\n\nProposal review supports `approve`\n\n, `reject`\n\nand `request_changes`\n\n. A `request_changes`\n\nreview sends the proposal back to `draft`\n\n; it is not a terminal side channel.\n\nModel-assisted proposal creation exists through `memory_propose_freeform`\n\nand `memory_propose_update`\n\n. Those entries may search and read context, then draft an ordinary proposal. They cannot review, apply or publish their own work.\n\nDirect `create`\n\n, `patch`\n\nand `rename`\n\nmutations are also available:\n\n- on the\n`standard`\n\nand`admin`\n\nsurfaces they are direct tools; - on the\n`curator`\n\nsurface they are**execute-only** operations reachable through`memory_execute`\n\nand catalog/workflow discovery.\n\nThere is no client-facing hard delete.\n\nLexical search, links and backlinks need no model. GTE-small adds semantic ranking; if it is unavailable, queries use lexical search. Details are in [ docs/semantic-search.md](/rcarmo/memento/blob/main/docs/semantic-search.md).\n\nNeedle handles a small set of read requests. Other model slots can write cited answers, draft proposals or suggest Dream maintenance work. Benchmarks are in [ docs/needle-performance.md](/rcarmo/memento/blob/main/docs/needle-performance.md), and upstream credits are in\n\n[.](/rcarmo/memento/blob/main/docs/attribution.md)\n\n`docs/attribution.md`\n\nA memory can carry an immutable, versioned asset pack in Git LFS. The searchable part stays in Markdown; diagrams, templates, datasets and complete agent skills travel in the attached ZIP.\n\nA skill is a normal concept under `/skills/`\n\n, tagged `skill`\n\n, whose body matches the `SKILL.md`\n\nin its attached pack. An `asset_kind=\"skill\"`\n\nZIP may contain scripts, references and binary assets, but not executable binaries, links, nested archives or unsafe paths.\n\n``` php\nstandard concept + attach_asset_pack proposal\n    -> ordinary curator review and apply\n    -> readers find it with memory_search and memory_read\n    -> memory_asset_get recalls a version\n    -> client imports into .pi/skills/<name>/\n```\n\nAsset versions use stable semantic versions and are stored by immutable concept ID, so renaming a memory does not break attachments. Omitted versions resolve to the highest accepted version. The newest five are retained by default, and pruning protects the latest version and versions referenced by active proposals.\n\n`memory_asset_get`\n\nreturns the ZIP and its file manifest. `memento-skill-import`\n\nchecks the pack again, writes it into a workspace in one move and refuses to overwrite an existing skill. Memento does not install, merge or run skills.\n\nOnly one Memento process may hold the repository writer lease. Changes are assembled in temporary Git worktrees and published to `main`\n\nonly if the base revision still matches. The readable checkout and indexes advance before success is returned, so callers can immediately read their writes.\n\nOn startup, Memento compares interrupted journal entries with Git and finishes recovery before serving requests. Backups contain the bare repository and a checksummed SQLite copy; worktrees, checkouts and search indexes are recreated.\n\nTool arguments, Markdown, links, retrieved text and model output are all untrusted. Memento rejects traversal, symlinks, special files, reserved-file writes, oversized changes, stale revisions, namespace violations and likely secrets in model-authored proposals.\n\nMemento supports Python 3.12-3.14 and ships as a non-root multi-architecture container. Start with [ examples/config.v1.json](/rcarmo/memento/blob/main/examples/config.v1.json), then follow\n\n[for tokens, deployment, health checks, backups and recovery.](/rcarmo/memento/blob/main/docs/operations.md)\n\n`docs/operations.md`\n\nFor development:\n\n```\nmake install-dev\nmake check\n```\n\nTagged releases are published to `ghcr.io/rcarmo/memento`\n\n. Build notes are in [ docs/release.md](/rcarmo/memento/blob/main/docs/release.md), and load-test results are in\n\n[.](/rcarmo/memento/blob/main/docs/load-testing.md)\n\n`docs/load-testing.md`\n\ntracks implementation status and pending work.`PLAN.md`\n\nrecords the implemented architecture.`docs/implementation.md`\n\nshows request, proposal, mutation, recovery, search, router and Dream transitions.`docs/diagrams.md`\n\nrecords consequential design decisions, including the`docs/decisions/`\n\n[Needle feasibility study](/rcarmo/memento/blob/main/docs/decisions/0002-needle-feasibility.md).defines schemas, envelopes and MCP operations.`docs/contracts.md`\n\nrecords trust boundaries and abuse cases.`docs/threat-model.md`\n\ncovers the Rust GTE and SQLite vector tier.`docs/semantic-search.md`\n\ncovers deployment, health, backup and recovery.`docs/operations.md`\n\ncovers the repository-owned load harness and local thresholds.`docs/load-testing.md`\n\ncontains local operational, HTTP and semantic reports.`docs/evidence/`\n\ndefines contribution and validation rules.`AGENTS.md`\n\n[ rcarmo/umcp](https://github.com/rcarmo/umcp) supplies Memento's MCP server, Streamable HTTP transport, request context and authentication hooks.\n\nMemento's semantic-search runtime started from [ rcarmo/go-gte](https://github.com/rcarmo/go-gte), whose model conversion, tokenizer and inference code provided the reference for the Rust port. The bundled GTE-small weights come from\n\n[.](https://huggingface.co/thenlper/gte-small)\n\n`thenlper/gte-small`\n\nThe shallow router builds on [ cactus-compute/needle](https://github.com/cactus-compute/needle) and its 26M-parameter checkpoint. Memento adds its routing dataset and checkpoint, NDL1 conversion, Rust inference code, SIMD kernels and C ABI.\n\nMemento is MIT licensed. Third-party runtime, model and artefact details are recorded in [ docs/attribution.md](/rcarmo/memento/blob/main/docs/attribution.md).", "url": "https://wpnews.pro/news/rcarmo-memento-a-cross-agent-memory-system", "canonical_source": "https://github.com/rcarmo/memento", "published_at": "2026-07-18 18:40:31+00:00", "updated_at": "2026-07-18 18:51:46.560835+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-infrastructure", "developer-tools", "artificial-intelligence"], "entities": ["Rui Carmo", "Memento", "Piclaw", "MCP", "cactus-compute/needle", "rcarmo/go-gte", "thenlper/gte-small", "rcarmo/umcp"], "alternates": {"html": "https://wpnews.pro/news/rcarmo-memento-a-cross-agent-memory-system", "markdown": "https://wpnews.pro/news/rcarmo-memento-a-cross-agent-memory-system.md", "text": "https://wpnews.pro/news/rcarmo-memento-a-cross-agent-memory-system.txt", "jsonld": "https://wpnews.pro/news/rcarmo-memento-a-cross-agent-memory-system.jsonld"}}