memento — rcarmo

/ 3

←/→ keyboard navigation

Memory graph overview

Visual debugger showing concepts, services, links, clusters and diagnostics

View full size ↗

Memory inspector

Selected concept metadata, links, assets, proposals and embedding state

View full size ↗

Large graph stress view

2,000-node graph with level-of-detail rendering and runtime diagnostics

View full size ↗

Overview<br>How it works<br>Features<br>Diagram

Overview

memento stores knowledge that should outlive a conversation and remain available to several agents: people, projects, machines, services, decisions and their relationships. Chats, reminders, credentials and machine-specific state stay with the agent that owns them.

It was built for several piclaw instances, but any authenticated MCP client can search, read and propose changes. Curators review writes before they reach the shared repository.

How it works

Concepts are Markdown files with stable IDs, metadata and links. Git owns those files and their history; control.sqlite owns proposals, idempotency records, write journals, leases and scheduler state. A separate FTS5, graph and optional vector index is derived from Markdown and can be rebuilt.

A fine-tuned local Needle model removes ambiguity by classifying natural-language requests into a small set of read operations. Deterministic code derives search text, IDs, paths and bounded plans, then applies schema validation and normal authorisation. The model cannot author mutations.

Writes follow search -> read -> propose -> review -> apply. Accepted changes are assembled in temporary worktrees and committed only if the expected repository revision still matches. The readable checkout and indexes advance before success is returned.

Features

Authenticated MCP access

umcp supplies Streamable HTTP transport, request context and authentication. Clients receive tools, not filesystem or Git access.

Fine-tuned request routing

A local Needle model classifies natural-language requests into bounded read operations. Strict schemas and deterministic expansion validate each result before execution.

Search without mandatory models

Lexical and graph search work locally. GTE-small can add semantic ranking; queries fall back to lexical search if it is unavailable.

Proposal-first writes

Agents draft changes and inspect diffs. Curators approve, reject or request changes; model-authored proposals cannot approve themselves.

Revision-safe Git history

Stable concept IDs survive renames, inbound links update in the same transaction and stale writes conflict instead of replacing newer knowledge.

Recallable asset packs

Versioned Git LFS ZIPs can attach diagrams, templates, datasets or complete skills to a concept, with manifests and path checks on recall.

Optional model assistance

Separate local models can produce cited answers, draft proposals and suggest Dream maintenance work. They remain advisory and cannot publish.

Recovery and backups

A single-writer lease, operation journal and startup reconciliation cover interrupted mutations. Backups contain the bare repository and a checksummed SQLite copy.

Explicit boundaries

No chat transcripts, reminders, credentials, hard delete, arbitrary shell execution or direct model writes.

Architecture

MCP clients<br>Piclaw · other agents

Memento MCP<br>auth · roles · tools

Reviewed writes<br>proposal · journal · lease

Fine-tuned router<br>bounded read operations

Git knowledge<br>Markdown · history · LFS

Derived indexes<br>FTS5 · graph · vectors

rebuild

Canonical Git knowledge, rebuildable search and reviewed writes