Collapse doc/ and docs/

2026-04-04 02:47:24 -04:00 · 2026-04-04 02:47:24 -04:00 · 6fa881f811
commit 6fa881f811
parent 79e384f005
6 changed files with 0 additions and 0 deletions
--- a/doc/memory.md
+++ b/doc/memory.md
@ -0,0 +1,123 @@
+# 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.