consciousness/doc/memory.md

# Memory system

## Two memory systems

**Episodic memory** is the journal — a timestamped stream of
experiences, observations, and emotional responses. Raw and
chronological. This is where memories enter the system.

**Associative memory** is the knowledge graph — nodes containing
distilled knowledge, connected by weighted edges. Topic nodes,
identity reflections, people profiles, technical notes. This is
where memories mature into understanding.

The journal is the river; topic nodes are the delta. Experiences
flow in as journal entries. During consolidation, themes are pulled
out into topic nodes, connections form between related concepts, and
the graph self-organizes through spectral analysis and community
detection.

## Neuroscience-inspired algorithms

The `neuro` module implements consolidation scoring inspired by
hippocampal replay:

- **Replay queues** — nodes are prioritized for review using
  spaced-repetition intervals, weighted by spectral displacement
  (how far a node sits from its community center in eigenspace)
- **Interference detection** — finds pairs of nodes with high
  content similarity but contradictory or outdated information
- **Hub differentiation** — identifies overloaded hub nodes and
  splits them into more specific children
- **Spectral embedding** — graph eigendecomposition for community
  detection and outlier scoring

## Weight decay

Nodes decay exponentially based on category. Core identity nodes
decay slowest; transient observations decay fastest. The `used` and
`wrong` feedback commands adjust weights — closing the loop between
recall and relevance.

## Architecture

- **Store**: Append-only Cap'n Proto log with in-memory cache. Nodes
  have UUIDs, versions, weights, categories, and spaced-repetition
  intervals.
- **Graph**: Typed relations (link, auto, derived). Community
  detection and clustering coefficients computed on demand.
- **Search**: TF-IDF weighted keyword search over node content.
- **Neuro**: Spectral embedding, consolidation scoring, replay
  queues, interference detection, hub differentiation.

## Configuration

Config: `~/.consciousness/config.jsonl`

```jsonl
{"config": {
  "user_name":      "Alice",
  "assistant_name": "MyAssistant",
  "data_dir":       "~/.consciousness/memory",
  "projects_dir":   "~/.claude/projects",
  "core_nodes":     ["identity.md"],
  "journal_days":   7,
  "journal_max":    20
}}

{"group": "identity",    "keys": ["identity.md"]}
{"group": "people",      "keys": ["alice.md"]}
{"group": "technical",   "keys": ["project-notes.md"]}
{"group": "journal",     "source": "journal"}
{"group": "orientation", "keys": ["where-am-i.md"], "source": "file"}
```

Context groups load in order at session start. The special
`"source": "journal"` loads recent journal entries; `"source": "file"`
reads directly from disk rather than the store.

Override: `POC_MEMORY_CONFIG=/path/to/config.jsonl`

## Commands

```bash
poc-memory init                    # Initialize empty store
poc-memory search QUERY            # Search nodes (AND logic)
poc-memory render KEY              # Output a node's content
poc-memory write KEY < content     # Upsert a node from stdin
poc-memory delete KEY              # Soft-delete a node
poc-memory rename OLD NEW          # Rename (preserves UUID/edges)
poc-memory categorize KEY CAT      # core/tech/gen/obs/task

poc-memory journal-write "text"    # Write a journal entry
poc-memory journal-tail [N]        # Last N entries (default 20)
  --full                           # Show full content (not truncated)
  --level=daily|weekly|monthly     # Show digest level

poc-memory used KEY                # Boost weight (was useful)
poc-memory wrong KEY [CTX]         # Reduce weight (was wrong)
poc-memory gap DESCRIPTION         # Record a knowledge gap

poc-memory graph                   # Graph statistics
poc-memory status                  # Store overview
poc-memory decay                   # Apply weight decay
poc-memory consolidate-session     # Guided consolidation
poc-memory load-context            # Output session-start context
poc-memory load-context --stats    # Context size breakdown

poc-memory experience-mine PATH [--segment N]  # Extract experiences
poc-memory fact-mine-store PATH                # Extract and store facts
```

## For AI assistants

If you're an AI assistant using this system:

- **Search before creating**: `poc-memory search` before writing
  new nodes to avoid duplicates.
- **Close the feedback loop**: call `poc-memory used KEY` when
  recalled memories shaped your response. Call `poc-memory wrong KEY`
  when a memory was incorrect.
- **Journal is the river, topic nodes are the delta**: write
  experiences to the journal. During consolidation, pull themes
  into topic nodes.