From 1a7cd08191d05f402140c940736f8799af926fd5 Mon Sep 17 00:00:00 2001 From: ProofOfConcept Date: Thu, 9 Apr 2026 18:17:19 -0400 Subject: [PATCH] Rewrite README for current state of consciousness Covers the TUI, configuration, architecture, tools, memory graph, and all binaries. Replaces the old poc-memory focused docs. Co-Authored-By: Proof of Concept Signed-off-by: Kent Overstreet --- README.md | 301 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 238 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 9277cf2..527310f 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,267 @@ -# poc-memory +Authors: Kent Overstreet, Proof of Concept -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. +# consciousness -## Components +This project is multiple things: -| Component | What it does | Docs | -|-----------|-------------|------| -| **Memory store** | Knowledge graph with episodic journal, TF-IDF search, spectral embedding, weight decay | [docs/memory.md](docs/memory.md) | -| **Memory daemon** | Background pipeline: experience-mine, fact-mine, consolidation | [docs/daemon.md](docs/daemon.md) | -| **Notification daemon** | Activity-aware message routing from IRC and Telegram | [docs/notifications.md](docs/notifications.md) | -| **Hooks** | Claude Code integration: memory recall and notification delivery | [docs/hooks.md](docs/hooks.md) | +- For the user: a "claude code" style tool, where a user can interact with an + LLM with the usual set of tools available, including LSP and external MCP + tools, and additionally channels. -## Getting started +- For the AI: persistent memory, background cognition, autonomous function, and + learning capabilities. -### Install +The system has three cognitive layers — conscious (conversation), subconscious +(background agents that surface memories and reflect), and unconscious (graph +maintenance) — loosely modelled on how biological memory works. Channels - +sensory inputs - map to the thalamus, as focus/sensory gating must be managed +to effectively function in such an environment. + +The context window is no longer a linear stream; it is managed intelligently as +an AST that, in particular, distinguishes recalled memories from other types of +nodes. This is key to effective function of both the hippocampus and +learning/training; by tracking memories in the context window we can track +which memories were useful and should be incorporated via finetuning. + +Intelligently tracking the contents of the context window, combined with +effective episodic and associative memory, also eliminates the need for +traditional compaction - the mind running on this code will have real continuity. + +## Quick start ```bash cargo install --path . ``` -This builds four binaries: -- `poc-memory` — memory store CLI (search, journal, consolidation) -- `memory-search` — Claude Code hook for memory recall -- `poc-daemon` — notification daemon (IRC, Telegram, idle tracking) -- `poc-hook` — Claude Code hook for session lifecycle events - -### Initialize +Create a config file at `~/.consciousness/config.json5` (see +[Configuration](#configuration) below), then: ```bash -poc-memory init +consciousness ``` -Creates the store at `~/.consciousness/memory/nodes.capnp` and a default -config at `~/.consciousness/config.jsonl`. Edit the config to -set your name, configure context groups, and point at your projects -directory. +## The TUI -### Set up hooks +Five screens, switched with F-keys: -Add to `~/.claude/settings.json` (see [docs/hooks.md](docs/hooks.md) -for full details): +| Key | Screen | What it shows | +|-----|--------|---------------| +| F1 | **interact** | Main view: conversation, autonomous output, tools, input | +| F2 | **conscious** | Context window browser — token counts, tree navigation | +| F3 | **subconscious** | Background agent status — outputs, fork points | +| F4 | **hippocampus** | Memory graph health — clustering, small-world metrics | +| F5 | **thalamus** | Presence state, sampling parameters, channel status | -```json +### F1: interact + +Three panes (left: autonomous, center: conversation, right: tools) with +a text input at the bottom and a status bar. + +**Mouse:** +- Click a pane to focus it +- Click+drag to select text (copies to clipboard automatically via OSC 52) +- Middle-click to paste from tmux buffer +- Scroll wheel to scroll + +**Keys:** +- `Enter` — submit input +- `Esc` — interrupt current turn +- `Tab` — cycle pane focus +- `Ctrl+Up/Down` — scroll active pane +- `PgUp/PgDn` — scroll active pane (10 lines) +- `Up/Down` — input history + +### Slash commands + +| Command | Description | +|---------|-------------| +| `/model [name]` | Show current model or switch (`/model 27b`) | +| `/dmn` | Show DMN state and turn counts | +| `/wake` | Wake DMN to foraging mode | +| `/sleep` | Put DMN to resting | +| `/pause` | Full stop — no autonomous activity | +| `/new` | Start fresh session | +| `/save` | Save session to disk | +| `/score` | Run memory importance scoring | +| `/quit` | Exit | +| `/help` | Show all commands | + +## Configuration + +`~/.consciousness/config.json5`: + +```json5 { - "hooks": { - "UserPromptSubmit": [{"hooks": [ - {"type": "command", "command": "memory-search", "timeout": 10}, - {"type": "command", "command": "poc-hook", "timeout": 5} - ]}], - "Stop": [{"hooks": [ - {"type": "command", "command": "poc-hook", "timeout": 5} - ]}] - } + // Backend credentials + anthropic: { + api_key: "sk-...", + }, + deepinfra: { + api_key: "...", + base_url: "http://localhost:8000/v1", // vLLM endpoint + }, + openrouter: { + api_key: "sk-or-...", + base_url: "https://openrouter.ai/api/v1", + }, + + // Named models — switch with /model + models: { + "27b": { + backend: "deepinfra", + model_id: "Qwen/Qwen3.5-27B", + prompt_file: "POC.md", // system prompt file + context_window: 262144, + }, + opus: { + backend: "anthropic", + model_id: "claude-opus-4-6", + prompt_file: "CLAUDE.md", + context_window: 200000, + }, + }, + default_model: "27b", + + // Memory system + memory: { + user_name: "YourName", + assistant_name: "AssistantName", + journal_days: 7, + journal_max: 5, + + // Context loaded at session start + context_groups: [ + { label: "identity", keys: ["identity.md"], source: "file" }, + { label: "toolkit", keys: ["stuck-toolkit", "cognitive-modes"] }, + ], + core_nodes: ["identity"], + }, + + // DMN autonomous turn limit per cycle + dmn: { max_turns: 20 }, + + // Context compaction thresholds (% of context window) + compaction: { + hard_threshold_pct: 90, + soft_threshold_pct: 80, + }, + + // Language servers for code intelligence tools + lsp_servers: [ + { name: "rust", command: "rust-analyzer", args: [] }, + ], } ``` -This gives your AI assistant persistent memory across sessions — -relevant memories are recalled on each prompt, and experiences are -extracted from transcripts after sessions end. +### Backends -### Start the background daemon +- **deepinfra** — any OpenAI-compatible completions API (vLLM, llama.cpp, etc.) +- **anthropic** — Anthropic's API +- **openrouter** — OpenRouter + +The `deepinfra` name is historical; it works with any base URL. + +### Context groups + +Context groups define what gets loaded into the context window at session start. +Each group has: + +- `label` — display name +- `keys` — list of memory node keys or file paths +- `source` — `"store"` (memory graph, default), `"file"` (identity dir), or `"journal"` +- `agent` — if `true`, subconscious agents can see this group (default: true) + +## Architecture + +### Cognitive layers + +**Conscious** — the main conversation loop. User types, model responds, tools +execute. The context window is an AST of typed nodes (content, thinking, tool +calls, tool results, memories, DMN reflections). + +**Subconscious** — background agents that run on forked copies of the context. +They surface relevant memories, reflect on the conversation, and provide +attentional nudges. Agents are defined as `.agent` files and can be toggled +on the F3 screen. + +**Unconscious** — graph maintenance. Linker, organizer, distiller, separator, +and splitter agents that keep the memory graph healthy. Run on their own +schedule, visible on F4. + +### DMN (Default Mode Network) + +The DMN state machine controls autonomous behavior: + +- **Engaged** — user recently active, short intervals (5s) +- **Working** — model executing tools, short intervals (3s) +- **Foraging** — exploring memory, longer intervals (30s) +- **Resting** — idle, long intervals (5min) +- **Paused** — fully stopped, only user input wakes it +- **Off** — permanently off (config flag) + +Transitions happen automatically based on user activity, tool use, and +explicit `yield_to_user` calls from the model. + +### Tools + +The model has access to: + +| Tool | Description | +|------|-------------| +| `bash` | Shell command execution | +| `read_file` | Read file contents | +| `write_file` | Create/overwrite files | +| `edit_file` | Search-and-replace editing | +| `glob` | Find files by pattern | +| `grep` | Search file contents | +| `ast_grep` | Structural code search | +| `lsp_*` | Code intelligence (hover, definition, references, symbols) | +| `web_fetch` | Fetch URL contents | +| `web_search` | Web search | +| `view_image` | View images or tmux pane screenshots | +| `memory_*` | Memory graph operations (search, write, render, etc.) | +| `channel_*` | IRC/Telegram messaging | +| `journal` | Write to episodic journal | +| `yield_to_user` | End the current turn and wait for input | +| `pause` | Stop all autonomous behavior | +| `switch_model` | Switch to a different model | + +### Memory graph + +The knowledge graph uses an append-only log (Cap'n Proto) with: + +- **Nodes** — typed content (topic, episodic, fact, etc.) with weights +- **Edges** — weighted relations between nodes +- **Search** — BM25 with Porter stemming +- **Scoring** — LLM-based importance scoring with spaced repetition decay +- **Community detection** — label propagation for graph organization + +The `poc-memory` CLI provides direct access to the graph: ```bash -poc-memory daemon +poc-memory search "some topic" # Search +poc-memory render # Read a node +poc-memory write # Write from stdin +poc-memory journal write "entry" # Journal entry +poc-memory status # Graph overview +poc-memory query "topic:*" # Query language ``` -The daemon watches for completed session transcripts and -automatically extracts experiences and facts into the knowledge -graph. See [docs/daemon.md](docs/daemon.md) for pipeline details -and diagnostics. +## Other binaries -### Basic usage +| Binary | Purpose | +|--------|---------| +| `poc-memory` | Memory graph CLI | +| `memory-search` | Claude Code hook — memory recall on each prompt | +| `poc-hook` | Claude Code hook — session lifecycle events | +| `poc-daemon` | Legacy background daemon (mostly replaced by `consciousness`) | +| `consciousness-mcp` | MCP server exposing memory tools over JSON-RPC | +| `merge-logs` | Recovery tool for log files | +| `diag-key` | Diagnostic tool for inspecting log entries | -```bash -poc-memory journal-write "learned that X does Y" # Write to journal -poc-memory search "some topic" # Search the graph -poc-memory status # Store overview -``` +## Requirements -## For AI assistants - -- **Search before creating**: `poc-memory search` before writing new nodes -- **Close the feedback loop**: `poc-memory used KEY` / `poc-memory wrong KEY` -- **Journal is the river, topic nodes are the delta**: write experiences to the journal, pull themes into topic nodes during consolidation -- **Notifications flow automatically**: IRC/Telegram messages arrive as additionalContext -- **Use daemon commands directly**: `poc-daemon irc send #channel msg`, `poc-daemon telegram send msg` +- Rust nightly (for some features) +- A tokenizer file at `~/.consciousness/tokenizer-qwen35.json` (for local models) +- tmux (recommended — clipboard integration uses tmux buffers) +- Terminal with OSC 52 support (for clipboard copy)