move README.md to toplevel

Co-Authored-By: ProofOfConcept <poc@bcachefs.org>

README.md

@@ -0,0 +1,173 @@
+# poc-memory
+
+A persistent memory system for AI assistants. Stores knowledge as a
+weighted graph of nodes and relations, with automatic recall via Claude
+Code hooks.
+
+## Quick start
+
+```bash
+# Install
+cargo install --path .
+
+# Initialize the store
+poc-memory init
+
+# Install Claude Code hooks and systemd service
+poc-memory daemon install
+```
+
+## Configuration
+
+Config file: `~/.config/poc-memory/config.toml`
+
+```toml
+# Names used in transcripts and agent prompts
+user_name = "Alice"
+assistant_name = "MyAssistant"
+
+# Where memory data lives (store, logs, episodic digests)
+data_dir = "~/.claude/memory"
+
+# Where Claude Code session transcripts are stored
+projects_dir = "~/.claude/projects"
+
+# Nodes that should never be decayed (comma-separated)
+core_nodes = "identity.md, preferences.md"
+
+# Journal settings for session-start context loading
+journal_days = 7
+journal_max = 20
+
+# Context groups loaded at session start, in order.
+# Each [context.NAME] section specifies a group of nodes to load.
+# If no "label" is given, the section name is used (underscores become spaces).
+[context.identity]
+keys = "identity.md"
+
+[context.people]
+keys = "alice.md, bob.md"
+
+[context.technical]
+keys = "project-notes.md, architecture.md"
+
+# Orientation loaded last — current task state, not deep identity
+[context.orientation]
+keys = "where-am-i.md"
+```
+
+Override the config path with `POC_MEMORY_CONFIG=/path/to/config.toml`.
+
+## Commands
+
+### Core operations
+
+```bash
+poc-memory init                    # Initialize empty store
+poc-memory search QUERY            # Search nodes (1-3 words, 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 a node (preserves UUID/edges)
+poc-memory categorize KEY CAT      # Set category: core/tech/gen/obs/task
+```
+
+### Journal
+
+```bash
+poc-memory journal-write "text"    # Write a journal entry
+poc-memory journal-tail [N]        # Show last N entries (default 20)
+poc-memory journal-tail N --full   # Show full content (not truncated)
+```
+
+### Feedback loop
+
+```bash
+poc-memory used KEY                # Mark a recalled node as useful (boosts weight)
+poc-memory wrong KEY [CONTEXT]     # Mark a node as wrong (reduces weight)
+poc-memory gap DESCRIPTION         # Record a knowledge gap for later filling
+```
+
+### Graph operations
+
+```bash
+poc-memory link N                  # Interactive graph walk from a node
+poc-memory graph                   # Show graph statistics
+poc-memory status                  # Store overview: node/edge counts, categories
+```
+
+### Maintenance
+
+```bash
+poc-memory decay                   # Apply weight decay to all nodes
+poc-memory consolidate-session     # Guided 6-step memory consolidation
+```
+
+### Context loading (used by hooks)
+
+```bash
+poc-memory load-context            # Output full session-start context
+```
+
+This loads all context groups from the config file in order, followed by
+recent journal entries. The `memory-search` hook binary calls this
+automatically on session start.
+
+### Daemon
+
+```bash
+poc-memory daemon                  # Run the background daemon
+poc-memory daemon install          # Install systemd service + Claude hooks
+```
+
+The daemon watches for completed Claude sessions and runs experience
+mining and fact extraction on transcripts.
+
+### Mining (used by daemon)
+
+```bash
+poc-memory experience-mine PATH    # Extract experiences from a transcript
+poc-memory fact-mine-store PATH    # Extract facts and store them
+```
+
+## How the hooks work
+
+The `memory-search` binary is a Claude Code `UserPromptSubmit` hook. On
+each prompt it:
+
+1. **First prompt of a session**: Runs `poc-memory load-context` to inject
+   full memory context (identity, reflections, journal, orientation).
+2. **Post-compaction**: Detects context compaction and reloads full context.
+3. **Every prompt**: Extracts keywords and searches the store for relevant
+   memories. Deduplicates against previously shown results for the session.
+
+Session state (cookies, seen-keys) is tracked in `/tmp/claude-memory-search/`
+and cleaned up after 24 hours.
+
+## Architecture
+
+- **Store**: Append-only Cap'n Proto log (`nodes.capnp`, `relations.capnp`)
+  with in-memory cache. Nodes have UUIDs, versions, weights, categories,
+  and spaced-repetition intervals.
+- **Graph**: Nodes connected by typed relations (link, auto, derived).
+  Community detection and clustering coefficients computed on demand.
+- **Search**: TF-IDF weighted keyword search over node content.
+- **Decay**: Exponential weight decay with category-specific factors.
+  Core nodes decay slowest; observations decay fastest.
+- **Daemon**: Uses jobkit for task scheduling with resource-gated LLM
+  access (one slot by default to manage API costs).
+
+## For AI assistants
+
+If you're an AI assistant using this system, here's what matters:
+
+- **Search before creating**: Always `poc-memory search` before writing
+  new nodes to avoid duplicates.
+- **Close the feedback loop**: When recalled memories shaped your response,
+  call `poc-memory used KEY`. When a memory was wrong, call
+  `poc-memory wrong KEY`. This trains the weight system.
+- **Journal is the river, topic nodes are the delta**: Write experiences
+  to the journal. During consolidation, pull themes into topic nodes.
+- **Config tells you who you are**: `poc-memory` reads your name from
+  the config file. Agent prompts use these names instead of generic
+  "the user" / "the assistant".