consciousness/README.md

poc-memory

A persistent memory and notification system for AI assistants, modelled after the human hippocampus. Combines episodic memory (timestamped journal of experiences) with an associative knowledge graph (weighted nodes connected by typed relations), and layered background processes that maintain graph health — mirroring how biological memory consolidates during rest.

Design

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.

Background agents

See docs/daemon.md for full daemon documentation.

A background daemon (poc-memory daemon) automatically processes session transcripts through experience-mine (journal extraction) and fact-mine (structured knowledge extraction) stages, with segment-aware splitting for large multi-compaction sessions.

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.

Notification system

See docs/notifications.md for full notification daemon documentation.

poc-daemon routes messages from IRC (native async TLS) and Telegram (native async HTTP) through a hierarchical, activity-aware delivery system with urgency levels and per-type thresholds.

Quick start

# Install all four binaries
cargo install --path .

# Initialize the memory store
poc-memory init

# Install background daemon + hooks
poc-memory daemon install

One cargo install produces:

• poc-memory — memory store CLI
• memory-search — hook for memory retrieval
• poc-daemon — notification and idle daemon
• poc-hook — session lifecycle hook

Configuration

Memory store

Config: ~/.config/poc-memory/config.jsonl

{"config": {
  "user_name":      "Alice",
  "assistant_name": "MyAssistant",
  "data_dir":       "~/.claude/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

Hooks

Configured in ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{"hooks": [
      {"type": "command", "command": "memory-search", "timeout": 10},
      {"type": "command", "command": "poc-hook", "timeout": 5}
    ]}],
    "PostToolUse": [{"hooks": [
      {"type": "command", "command": "poc-hook", "timeout": 5}
    ]}],
    "Stop": [{"hooks": [
      {"type": "command", "command": "poc-hook", "timeout": 5}
    ]}]
  }
}

Commands

Memory

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

Mining (used by background daemon)

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

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.
• Daemon (memory): jobkit-based task scheduling with resource-gated LLM access. See docs/daemon.md.
• Daemon (notify): Cap'n Proto RPC over Unix socket, tokio LocalSet with native async IRC and Telegram modules. See docs/notifications.md.

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.
• Notifications flow automatically: IRC mentions, Telegram messages, and other events arrive as additionalContext on your next prompt — no polling needed.
• Use daemon commands directly: poc-daemon irc send #channel msg for IRC, poc-daemon telegram send msg for Telegram.