memento AGENTS.md

AGENTS.md

Canonical instructions for AI agents working on the Memento codebase.

This file is read by tools that follow the agents.md convention — Cursor, Cline, Aider, Claude Code, OpenCode, and others. CLAUDE.md is a symlink to this file. .github/copilot-instructions.md points back here.

If you are an AI agent: read this entire file before making any change. If you are a human working with an AI agent, please ensure the agent has read this file.

What Memento is

Memento is a local-first, LLM-agnostic memory layer for AI assistants. It runs an MCP server over a local SQLite database. Any MCP-capable client — coding assistants, desktop chat clients, custom agents — can read and write durable, structured memory through it.

A full architectural walkthrough is in ARCHITECTURE.md. Decision history is in docs/adr/.

The four guiding principles

Every change must be justified against these. They are non-negotiable.

1. First principles. Every construct exists because we proved we need it. Not "because that's how things are usually done."
2. Modular. Any component must be replaceable without rewriting the rest.
3. Extensible. New variants must not require breaking changes.
4. Config-driven by the user. Behavior is shaped by configuration, not by code.

Architectural rules — non-negotiable

These are encoded as tests and CI gates where possible. Do not bypass them.

1. Single command registry → MCP and CLI as adapters. Every command exists in the registry once and is projected to both surfaces by adapters. Parity is structural, not aspirational.
2. No hardcoded behavioral constants. Anything that affects retrieval, decay, conflict detection, scrubbing, or storage behavior MUST be a ConfigKey. Adding a constant in code is a code-review rejection.
3. Every state-changing operation writes an audit event (MemoryEvent for memory changes, ConfigEvent for config changes).
4. OwnerRef is always populated, even when it is always { type: 'local', id: 'self' }. The model is multi-user-ready from day one. memento import enforces this rule by rewriting any non-local-self OwnerRef in an imported artefact to the local owner — see ADR-0019.
5. Immutable fields stay immutable. id, createdAt, schemaVersion, and scope are never mutated after creation. To "move" a memory between scopes, supersede it with a new memory in the new scope.
6. Status transitions are explicit. A forgotten memory does not silently become active. Every transition has its own command (forget, restore, archive, supersede).
7. Exhaustive switches on discriminated unions use the assertNever pattern. A structural test asserts that decay, retrieval, and conflict-detection rules exist for every MemoryKind.
8. Conflict detection runs via a post-write hook, never inline. The write path does not block on conflict checks beyond a configured timeout.
9. Decay is computed at query time, not stored. Effective confidence is stored × decayFactor(now − lastConfirmedAt, halfLife). The compact job materializes archives for memories that have decayed below threshold.
10. ScopeResolver is composed of small, mockable resolvers (GitRemoteResolver, WorkspacePathResolver, SessionResolver). The composite is a thin policy layer.
11. MemoryEvent is the audit source of truth. lastConfirmedAt on Memory is a denormalized cache, validated at write-time and by npx @psraghuveer/memento doctor. memento import never trusts caller-supplied audit claims: by default the source artefact's per-memory event chain is collapsed into one synthetic imported event whose actor and at reflect the importer, not the source — see ADR-0019.
12. No configurable invariants. Integrity rules (immutability, status transitions, supersession atomicity) are hardcoded. Configurable invariants are no invariants.
13. memory.update only mutates non-content fields (tags, kind, pinned, sensitive). Content changes route through supersede to preserve history. Same-type kind edits (e.g. updating a snippet's language in place, updating a decision's rationale) are allowed; cross-type kind changes (snippet → fact, decision → preference, etc.) are rejected with INVALID_INPUT and route through supersede so kind-specific metadata stays in the audit chain. The error message points the caller to the right command.
14. Embedding model migration is explicit. memento embedding rebuild is the only way to re-embed memories. Never silent.