# Lantern Memory Substrate v0
## Goal
Move Lantern one layer above transcript RAG without turning it into the whole agent runtime.
Lantern should remain the local-first, inspectable persistence and retrieval substrate. It should store raw evidence and first-class memory records. Omniplex should decide when to create, promote, revise, activate, and inject those memories.
## Non-goals for v0
- No autonomous cognitive architecture inside Lantern.
- No hidden salience model that lives only in embeddings.
- No automatic contradiction resolution.
- No long-running agent loop.
- No opaque context assembly.
## Core distinction
### Evidence
Evidence is raw material the system observed.
Examples:
- transcripts
- markdown notes
- source files
- tool outputs
- logs
- imported documents
Evidence is appendable or re-ingestable, chunked, searchable, and provenance-heavy.
Lantern already supports this through sources, chunks, metadata, entities, search, embeddings, and MCP surfaces.
### Memory record
A memory record is an explicit durable state object derived from evidence or direct operator intent.
Examples:
- user preference
- stable fact
- active goal
- constraint
- observation
- hypothesis
- task state
A memory record is not just another transcript chunk. It has lifecycle, priority, status, confidence, scope, and source references.
## Embeddings and importance
Embeddings answer: what is this about?
They are useful for semantic similarity, clustering, duplicate detection, and candidate recall. They should not be trusted to encode urgency or importance.
Importance must be explicit and inspectable. v0 should represent it as fields on memory records, then let retrieval policy combine those fields with semantic relevance.
## Responsibility split
### Lantern owns
- storage for evidence and memory records
- CRUD-style memory write/read operations
- schema migrations
- deterministic IDs
- status, type, scope, priority, confidence, timestamps
- source/evidence references
- keyword and field-filtered memory retrieval
- later: optional embedding over memory record text
- CLI, JSON, and MCP surfaces
- inspect/export/show visibility
### Omniplex owns
- deciding what should become memory
- promotion from transcript/evidence to memory record
- priority and urgency heuristics
- active-state assembly before actions
- post-action writeback
- contradiction detection and resolution workflow
- context injection policy
- review loops and reminders
## v0 memory object schema
A v0 record should be intentionally small.
Required fields:
- `id`: deterministic or generated stable ID
- `kind`: one of `fact`, `preference`, `goal`, `constraint`, `task_state`, `observation`, `hypothesis`
- `content`: human-readable memory text
- `scope`: string namespace such as `global`, `user:raphael`, `project:lantern`, `host:zettabyte`
- `priority`: integer 0-100, default 50
- `confidence`: float 0.0-1.0, default 1.0 for explicit writes
- `status`: one of `active`, `archived`, `superseded`
- `created_at`: unix timestamp
- `updated_at`: unix timestamp
Optional fields:
- `urgency`: integer 0-100, default 0
- `expires_at`: unix timestamp for temporary state
- `supersedes_id`: prior memory record replaced by this one
- `source_refs`: JSON array of source/chunk/session references
## v0 CLI shape
Start with the smallest useful writable interface.
```bash
lantern memory add \
--kind preference \
--scope user:raphael \
--priority 90 \
--confidence 1.0 \
"Raphael prefers separate branches on his repos."
lantern memory list --scope user:raphael --status active
lantern memory archive <id>
```
JSON output should be available for every memory command.
## v0 MCP shape
Expose the same primitive write/read operations.
- `lantern_memory_add`
- `lantern_memory_list`
- `lantern_memory_archive`
Do not put promotion policy in MCP tools. Let callers decide.
## v0 retrieval policy
Lantern should provide raw sorted/filterable results, not final cognitive policy.
Initial order for `memory list`:
1. active status first by default
2. higher priority
3. higher urgency
4. newer `updated_at`
5. deterministic `id`
Omniplex can later ask Lantern for candidate sets and apply its own activation policy.
## First implementation slice
Implement only:
- schema table `memory_records`
- Rust module `memory.rs`
- CLI `lantern memory add/list/archive`
- tests for add/list/archive and default ordering
Defer:
- semantic embeddings for memory records
- source reference validation
- supersede command
- MCP memory tools
- Omniplex promotion loop
## Acceptance criteria for first slice
- Existing stores migrate safely.
- New stores include `memory_records`.
- `memory add` writes a record and returns it.
- `memory list` returns active records ordered by priority/urgency/update time.
- `memory archive <id>` marks a record archived without deleting it.
- JSON output is stable.
- Full `cargo test` passes.