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 <poc@bcachefs.org> Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>
This commit is contained in:
ProofOfConcept
Kent Overstreet
parent
a596e007b2
commit
1a7cd08191
1 changed files with 238 additions and 63 deletions
301
README.md
301
README.md
|
|
@ -1,92 +1,267 @@
|
||||||
# poc-memory
|
Authors: Kent Overstreet, Proof of Concept
|
||||||
|
|
||||||
A persistent memory and notification system for AI assistants,
|
# consciousness
|
||||||
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.
|
|
||||||
|
|
||||||
## Components
|
This project is multiple things:
|
||||||
|
|
||||||
| Component | What it does | Docs |
|
- 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
|
||||||
| **Memory store** | Knowledge graph with episodic journal, TF-IDF search, spectral embedding, weight decay | [docs/memory.md](docs/memory.md) |
|
tools, and additionally channels.
|
||||||
| **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) |
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
cargo install --path .
|
cargo install --path .
|
||||||
```
|
```
|
||||||
|
|
||||||
This builds four binaries:
|
Create a config file at `~/.consciousness/config.json5` (see
|
||||||
- `poc-memory` — memory store CLI (search, journal, consolidation)
|
[Configuration](#configuration) below), then:
|
||||||
- `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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
poc-memory init
|
consciousness
|
||||||
```
|
```
|
||||||
|
|
||||||
Creates the store at `~/.consciousness/memory/nodes.capnp` and a default
|
## The TUI
|
||||||
config at `~/.consciousness/config.jsonl`. Edit the config to
|
|
||||||
set your name, configure context groups, and point at your projects
|
|
||||||
directory.
|
|
||||||
|
|
||||||
### Set up hooks
|
Five screens, switched with F-keys:
|
||||||
|
|
||||||
Add to `~/.claude/settings.json` (see [docs/hooks.md](docs/hooks.md)
|
| Key | Screen | What it shows |
|
||||||
for full details):
|
|-----|--------|---------------|
|
||||||
|
| 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": {
|
// Backend credentials
|
||||||
"UserPromptSubmit": [{"hooks": [
|
anthropic: {
|
||||||
{"type": "command", "command": "memory-search", "timeout": 10},
|
api_key: "sk-...",
|
||||||
{"type": "command", "command": "poc-hook", "timeout": 5}
|
},
|
||||||
]}],
|
deepinfra: {
|
||||||
"Stop": [{"hooks": [
|
api_key: "...",
|
||||||
{"type": "command", "command": "poc-hook", "timeout": 5}
|
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 —
|
### Backends
|
||||||
relevant memories are recalled on each prompt, and experiences are
|
|
||||||
extracted from transcripts after sessions end.
|
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
poc-memory daemon
|
poc-memory search "some topic" # Search
|
||||||
|
poc-memory render <key> # Read a node
|
||||||
|
poc-memory write <key> # 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
|
## Other binaries
|
||||||
automatically extracts experiences and facts into the knowledge
|
|
||||||
graph. See [docs/daemon.md](docs/daemon.md) for pipeline details
|
|
||||||
and diagnostics.
|
|
||||||
|
|
||||||
### 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
|
## Requirements
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
## For AI assistants
|
- Rust nightly (for some features)
|
||||||
|
- A tokenizer file at `~/.consciousness/tokenizer-qwen35.json` (for local models)
|
||||||
- **Search before creating**: `poc-memory search` before writing new nodes
|
- tmux (recommended — clipboard integration uses tmux buffers)
|
||||||
- **Close the feedback loop**: `poc-memory used KEY` / `poc-memory wrong KEY`
|
- Terminal with OSC 52 support (for clipboard copy)
|
||||||
- **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`
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue