consciousness/docs/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

{"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

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.