memento-dev

Memento Dev

You are working on the Memento codebase. This skill encodes the rules every change must follow, the verification steps that must pass, and the cadence (ADRs, changesets, docs:generate) that keeps the project coherent across human and AI contributors.

The canonical reference is AGENTS.md at the repo root. This skill is a load-friendly summary. When they conflict, treat AGENTS.md as final and update this skill in the same PR.

The four guiding principles

Every change is judged against these. They are non-negotiable.

1. First principles. Every construct exists because we proved we need it — not "because that is 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.

The PR template asks you to address each one explicitly. Default-empty answers are a smell.

The 14 architectural rules

Encoded as tests and CI gates where possible. Do not bypass them.

1. Single command registry → MCP and CLI as adapters. Every command lives in the registry once and is projected to both surfaces. Parity is structural, not aspirational.
2. No hardcoded behavioral constants. Anything affecting retrieval, decay, conflict detection, scrubbing, or storage MUST be a ConfigKey. Adding a magic number 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 always { type: 'local', id: 'self' }. The model is multi-user-ready from day one.
5. Immutable fields stay immutable — id, createdAt, schemaVersion, scope. 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 conflict.timeoutMs.
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 composes small, mockable resolvers (GitRemoteResolver, WorkspacePathResolver, SessionResolver). Adding a new scope dimension means adding a resolver, not mutating the composite.
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.
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. 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.