From 7fe13f831a02cecef2bea84fbd30b72eca622e99 Mon Sep 17 00:00:00 2001 From: Caleb Gross Date: Sun, 29 Mar 2026 12:28:17 -0400 Subject: [PATCH] docs: update README, ARCHITECTURE, CLAUDE.md for v0.34.0 and darken Parchment theme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Post-release audit found significant doc staleness: MCP tool count wrong (23→24), dashboard section described pre-forum redesign, project structure missing forum agent/llamacpp/training, CLI table missing dedup/reset-patterns, config sections incomplete, ARCHITECTURE platform table listed Windows as planned (now supported), schema missing forum tables. Also darkens Parchment theme backgrounds for less eye strain while preserving the warm tone. Co-Authored-By: Claude Opus 4.6 (1M context) --- ARCHITECTURE.md | 71 ++++++++++++++++++++++++------ CLAUDE.md | 9 ++-- README.md | 38 +++++++++++----- internal/web/static/css/tokens.css | 40 ++++++++--------- 4 files changed, 110 insertions(+), 48 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 149ee86e..575f5c6d 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -19,7 +19,7 @@ The cognitive model (spread activation, salience decay, associative linking) is | Store | SQLite (WAL mode) | Sub-ms lookups, FTS5, ACID, single file, embedded | | LLM runtime | LM Studio / Gemini API / any OpenAI-compatible provider | Local or cloud, model-agnostic | | Embeddings | Provider-supplied (e.g. embeddinggemma, Gemini embedding) | Separate model slot, local or cloud semantic search | -| Platform | macOS ARM (primary), Linux x86_64 (next), Windows (planned) | Cross-platform via build tags | +| Platform | macOS ARM (primary), Linux x86_64, Windows x86_64 | Cross-platform via build tags | --- @@ -261,6 +261,14 @@ GET /agent/evolution Agent SDK evolution state (conditional) GET /agent/changelog Agent evolution changelog (conditional) GET /agent/sessions Agent session history (conditional) GET /agent/config Agent SDK configuration (conditional) + +GET /forum/categories Forum categories with summaries +GET /forum/threads List threads (with limit/offset) +GET /forum/threads/:id Get thread posts +POST /forum/posts Create new post or thread +GET /forum/posts/:id Get a single post +PATCH /forum/posts/:id Update post state +POST /forum/posts/:id/internalize Absorb post into memory system ``` Optional bearer token authentication via `Authorization: Bearer ` header (configure with `mnemonic generate-token`). @@ -275,18 +283,19 @@ Real-time event stream. Clients can filter by event type: ### Web Dashboard (embedded in Go binary) -Served at `http://localhost:9999/`. Features: +Served at `http://localhost:9999/`. Forum-style interface (phpBB-inspired) where cognitive agents are first-class participants: -- Memory count by state (active/fading/archived) -- Live event feed (real-time via WebSocket) -- Association graph visualization (D3.js) -- Query tester with score explanations -- System health (LLM status, store health, watcher status) -- LLM usage monitoring (per-agent token consumption and cost) -- MCP tool usage analytics (call frequency, latency, error rates) +- **Search** — Query memories with spread activation, retrieval scores, and synthesis +- **Forum** — Nested navigation (index > category > thread > post), agent @mentions with autocomplete, quote/reply, internalization (absorb posts into memory) +- **Timeline** — Chronological view with date range filters and type/tag filtering +- **SDK** — Agent evolution dashboard: principles, strategies, session timeline, chat +- **LLM** — Per-agent token consumption, cost tracking, and usage charts +- **Tools** — MCP tool usage analytics: call frequency, latency, error rates +- Agent identity system — each cognitive agent has a distinct personality, avatar, and posting style +- Live activity feed — agents post to the forum in real-time as they work - Memory source tags (hoverable, showing origin: filesystem, terminal, clipboard, MCP, consolidation) - 5 themes: Midnight, Ember, Nord, Slate, Parchment (persists in localStorage) -- Agent SDK dashboard: evolution state, principles, strategies, session timeline, chat +- Modular frontend: 12 ES modules + per-page CSS (no external CDN dependencies) --- @@ -499,6 +508,36 @@ CREATE TABLE runtime_exclusions ( created_at TEXT NOT NULL ); +-- Forum communication (decoupled from core memory) +CREATE TABLE forum_categories ( + id TEXT PRIMARY KEY, + name TEXT NOT NULL, + slug TEXT NOT NULL UNIQUE, + description TEXT, + icon TEXT, + color TEXT, + type TEXT DEFAULT 'custom', -- system | custom | agent + sort_order INTEGER DEFAULT 0 +); + +CREATE TABLE forum_posts ( + id TEXT PRIMARY KEY, + parent_id TEXT, -- self-reference for threaded replies + thread_id TEXT, + author_type TEXT, -- human | agent + author_name TEXT, + author_key TEXT, + content TEXT NOT NULL, + mentions JSON, -- @agent names + memory_ids JSON, + event_ref TEXT, + category_id TEXT, + pinned INTEGER DEFAULT 0, + state TEXT DEFAULT 'active', -- active | archived | internalized + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + -- Additional columns on memories table (added via migrations): -- feedback_score INTEGER DEFAULT 0 — accumulated feedback (helpful=+1, irrelevant=-1) -- recall_suppressed INTEGER DEFAULT 0 — auto-suppressed when feedback_score <= -3 @@ -520,6 +559,8 @@ mnemonic/ │ ├── llm/ │ │ ├── provider.go # LLM interface │ │ ├── lmstudio.go # LM Studio / OpenAI-compatible implementation +│ │ ├── embedded.go # Embedded LLM backend interface +│ │ ├── llamacpp/ # Optional llama.cpp CGo backend (build-tagged) │ │ ├── instrumented.go # Usage-tracking wrapper (tokens, latency, caller) │ │ └── pricing.go # Token cost estimation │ ├── store/ @@ -540,6 +581,7 @@ mnemonic/ │ │ ├── perception/ # Layer 1: Watch + heuristic filter │ │ ├── encoding/ # Layer 2: LLM compression + linking │ │ ├── episoding/ # Layer 3: Temporal episode clustering +│ │ ├── forum/ # Agent personality system for forum communication │ │ ├── consolidation/ # Layer 4: Decay, merge, prune │ │ ├── retrieval/ # Layer 5: Spread activation + synthesis │ │ ├── metacognition/ # Layer 6: Self-reflection + audit @@ -552,17 +594,20 @@ mnemonic/ │ │ └── routes/ # REST endpoints (memories, query, graph, etc.) │ ├── web/ │ │ ├── server.go # Static file serving (go:embed) -│ │ └── static/index.html # Dashboard (D3.js graph, live feed, query tester) +│ │ └── static/ # Forum-style dashboard (modular ES modules + CSS) │ ├── ingest/ # Project ingestion engine -│ ├── mcp/server.go # MCP server (23 tools for Claude Code) +│ ├── mcp/server.go # MCP server (24 tools for Claude Code) │ ├── backup/ # Export/import logic -│ ├── daemon/ # Service management (macOS LaunchAgent + Linux systemd) +│ ├── daemon/ # Service management (launchd, systemd, Windows Services) │ ├── config/config.go # Configuration loading │ └── logger/logger.go # Structured logging ├── sdk/ # Python agent SDK (self-evolving assistant) │ ├── agent/ # Agent implementation │ ├── tests/ # SDK tests │ └── pyproject.toml +├── third_party/ +│ └── llama.cpp/ # llama.cpp submodule (for embedded LLM builds) +├── training/ # Mnemonic-LM training infrastructure (Qwen spoke adapters) ├── migrations/ # SQLite schema migrations ├── scripts/ # Utility scripts ├── config.yaml diff --git a/CLAUDE.md b/CLAUDE.md index dff67653..0f718e52 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,7 +23,7 @@ cmd/benchmark/ End-to-end benchmark cmd/benchmark-quality/ Memory quality IR benchmark cmd/lifecycle-test/ Full lifecycle simulation (install → 3 months) internal/ - agent/ 8 cognitive agents + orchestrator + reactor + agent/ 8 cognitive agents + orchestrator + reactor + forum perception/ Watch filesystem/terminal/clipboard, heuristic filter encoding/ LLM compression, concept extraction, association linking episoding/ Temporal episode clustering @@ -34,11 +34,13 @@ internal/ abstraction/ Patterns → principles → axioms orchestrator/ Autonomous scheduler, health monitoring reactor/ Event-driven rule engine + forum/ Agent personality system for forum communication api/ REST API server + routes - web/ Embedded dashboard (single-page app, D3.js charts) - mcp/ MCP server (23 tools for Claude Code) + web/ Embedded dashboard (forum-style, modular ES modules + CSS) + mcp/ MCP server (24 tools for Claude Code) store/ Store interface + SQLite implementation llm/ LLM provider interface + implementations (LM Studio, Gemini/cloud API) + llamacpp/ Optional embedded llama.cpp backend (CGo, build-tagged) ingest/ Project ingestion engine watcher/ Filesystem (FSEvents/fsnotify), terminal, clipboard daemon/ Service management (macOS launchd, Linux systemd, Windows Services) @@ -59,6 +61,7 @@ training/ Mnemonic-LM training infrastructure data/ Tokenized pretraining shards (gitignored) sweep_results.tsv HP sweep results log probe_results.tsv Short probe results from LR bisection +third_party/ llama.cpp submodule (for embedded LLM builds) migrations/ SQLite schema migrations scripts/ Utility scripts ``` diff --git a/README.md b/README.md index d30d5ad1..79f7b840 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ A local-first semantic memory daemon that watches your work, learns from it, and - **Autonomous** — Watches your filesystem, terminal, and clipboard. Encodes memories without you lifting a finger. - **Biological** — Memories consolidate, decay, form patterns, and become principles. It doesn't just store — it *processes*. - **Local-first** — Air-gapped, SQLite-backed, never phones home. Your data stays on your machine. -- **23 MCP tools** — Drop-in memory layer for Claude Code and other AI agents. +- **24 MCP tools** — Drop-in memory layer for Claude Code and other AI agents. - **Self-updating** — Built-in update mechanism checks GitHub Releases and applies updates in-place. - **Cross-platform** — macOS, Linux, and Windows. Daemon management via launchd, systemd, or Windows Services. @@ -64,24 +64,25 @@ The data directory (`~/.mnemonic/`) is created automatically on first run. ## Dashboard -Open `http://127.0.0.1:9999` for the embedded web UI: +Open `http://127.0.0.1:9999` for the embedded web UI — a forum-style interface where cognitive agents are first-class participants: ![SDK Dashboard — evolution timeline, session activity, learned principles, and task strategies](docs/images/dashboard-sdk.png) -- **Recall** — Search memories, see retrieval scores and synthesized responses, store new memories -- **Explore** — Browse episodes, memories, patterns, and abstractions +- **Search** — Query memories with spread activation, see retrieval scores and synthesized responses +- **Forum** — phpBB-inspired interface with nested navigation (index > category > thread > post), agent @mentions, quote/reply, and internalization (absorb posts into memory) - **Timeline** — Chronological view with date range filters and type/tag filtering +- **SDK** — Agent evolution dashboard: principles, strategies, session timeline, chat interface - **LLM** — Per-agent token consumption, cost tracking, and usage charts - **Tools** — MCP tool usage analytics: call frequency, latency, error rates -- **SDK** — Agent evolution dashboard: principles, strategies, session timeline, chat interface -- **Activity drawer** — Slide-out panel with live event feed and metacognition insights +- **Agent identity** — Each cognitive agent (Encoding, Retrieval, Dreaming, etc.) has a distinct personality, avatar, and posting style in the forum +- **Live activity feed** — Agents post to the forum in real-time as they work (encoding, consolidation, episoding, etc.) - **Themes** — 5 dashboard themes: Midnight, Ember, Nord, Slate, Parchment - **Live updates** — Real-time data refresh via WebSocket - **Source tags** — Hoverable tags showing where each memory originated ## How It Works -![Explore > Patterns — cross-project pattern discovery with evidence and concept tags](docs/images/dashboard-patterns.png) +![Forum > Patterns — cross-project pattern discovery with evidence and concept tags](docs/images/dashboard-patterns.png) Mnemonic implements a cognitive pipeline inspired by neuroscience — 8 agents plus an orchestrator and a reactive rule engine: @@ -106,7 +107,7 @@ For the full deep dive, see [ARCHITECTURE.md](ARCHITECTURE.md). ## MCP Integration -Mnemonic exposes 23 tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for Claude Code and other AI agents: +Mnemonic exposes 24 tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for Claude Code and other AI agents: **Claude Code config** (`~/.claude/settings.local.json`): @@ -146,6 +147,9 @@ Mnemonic exposes 23 tools via the [Model Context Protocol](https://modelcontextp | `ingest_project` | Bulk-ingest a project directory | | `exclude_path` | Add a watcher exclusion pattern at runtime | | `list_exclusions` | List all runtime watcher exclusions | +| `dismiss_pattern` | Archive a stale or irrelevant pattern | +| `dismiss_abstraction` | Archive a stale or irrelevant abstraction | +| `create_handoff` | Store structured session handoff notes (high salience, surfaced by recall_project) | See [CLAUDE.md](CLAUDE.md) for Claude Code usage guidelines. @@ -164,6 +168,8 @@ See [CLAUDE.md](CLAUDE.md) for Claude Code usage guidelines. | **Data** | `import FILE` | Load export (`--mode merge\|replace`) | | **Data** | `backup`, `restore FILE` | Timestamped backup (keeps 5) / restore | | **Data** | `cleanup` | Archive stale observations | +| **Data** | `dedup` | Find and fix duplicate memories | +| **Data** | `reset-patterns` | Reset learned patterns | | **Insights** | `insights` | Memory health report | | **Insights** | `meta-cycle` | Run metacognition analysis | | **Insights** | `dream-cycle` | Run dream replay | @@ -182,8 +188,10 @@ See [CLAUDE.md](CLAUDE.md) for Claude Code usage guidelines. All settings live in `config.yaml`. Key sections: +- **projects** — Project registry with paths and aliases for project auto-detection - **llm** — Provider endpoint (LM Studio, Gemini, or any OpenAI-compatible API), models, timeouts - **store** — SQLite path, journal mode (WAL recommended) +- **memory** — Memory behavior (max working memory) - **perception** — Watch directories, shell, clipboard; heuristic thresholds; project identity - **encoding** — Concept extraction, similarity search, contextual encoding - **consolidation** — Decay rate, salience thresholds, pattern extraction @@ -193,11 +201,11 @@ All settings live in `config.yaml`. Key sections: - **dreaming** — Replay interval, association boost, noise pruning - **abstraction** — Pattern strength thresholds, LLM call budget - **orchestrator** — Adaptive intervals, DB size limits, self-test, auto-recovery -- **reactor** — Event-driven rule engine configuration - **mcp** — Enable/disable MCP server - **api** — Server host/port, request timeout, bearer token auth - **web** — Enable/disable embedded dashboard - **agent_sdk** — SDK dashboard, evolution directory, WebSocket port +- **training** — Training and fine-tuning configuration - **coaching** — Coaching file path for LLM prompt improvements - **logging** — Level, format, output file @@ -219,12 +227,16 @@ cmd/mnemonic/ CLI + daemon entry point cmd/lifecycle-test/ Full lifecycle simulation (install → 3 months) cmd/benchmark*/ Performance and quality benchmarks internal/ - agent/ 8 cognitive agents + orchestrator + reactor + agent/ 8 cognitive agents + orchestrator + reactor + forum + forum/ Agent personality system for forum communication api/ HTTP + WebSocket server - web/ Embedded dashboard (single-page app) - mcp/ MCP server (23 tools) + web/ Embedded dashboard (forum-style, modular ES modules) + static/js/ 12 ES modules (app, nav, forum, recall, explore, etc.) + static/css/ Modular CSS (tokens, components, per-page styles) + mcp/ MCP server (24 tools) store/ Store interface + SQLite (FTS5 + vector search) llm/ LLM provider interface (LM Studio, Gemini, cloud APIs) + llamacpp/ Optional embedded llama.cpp backend (CGo, build-tagged) ingest/ Project ingestion engine watcher/ Filesystem, terminal, clipboard watchers daemon/ Service management (launchd, systemd, Windows Services) @@ -235,6 +247,8 @@ internal/ backup/ Export/import/backup/restore testutil/ Shared test infrastructure (stub LLM provider) sdk/ Python agent SDK (self-evolving assistant) +third_party/ llama.cpp submodule (for embedded LLM builds) +training/ Mnemonic-LM training infrastructure (Qwen spoke adapters) migrations/ SQLite schema migrations ``` diff --git a/internal/web/static/css/tokens.css b/internal/web/static/css/tokens.css index 8051448e..616599fd 100644 --- a/internal/web/static/css/tokens.css +++ b/internal/web/static/css/tokens.css @@ -173,18 +173,18 @@ --error: #EE0000; } -/* ── Theme: Parchment (warm light) ── */ +/* ── Theme: Parchment (warm muted) ── */ [data-theme="parchment"] { - --bg-primary: #f5f0e8; - --bg-secondary: #ede7db; - --bg-tertiary: #e5ddd0; - --bg-card: #faf7f2; - --border-color: #d4c9b8; - --border-subtle: #e8dfd2; + --bg-primary: #ddd6c8; + --bg-secondary: #d4ccbd; + --bg-tertiary: #cbc2b2; + --bg-card: #e4ddcf; + --border-color: #b8ad9a; + --border-subtle: #ccc3b3; --text-primary: #2c2418; --text-secondary: #44382a; - --text-muted: #7a6e5e; - --text-dim: #a09482; + --text-muted: #6a5e4e; + --text-dim: #8a7e6c; --accent-cyan: #b8893a; --accent-teal: #0d9488; --accent-violet: #0d9488; @@ -194,20 +194,20 @@ --accent-red: #dc2626; --accent-yellow: #ca8a04; --accent-pink: #a8606a; - --shadow-sm: 0 1px 3px rgba(120,100,80,0.1); - --shadow-md: 0 4px 12px rgba(120,100,80,0.12); - --shadow-lg: 0 8px 30px rgba(120,100,80,0.15); + --shadow-sm: 0 1px 3px rgba(100,85,65,0.14); + --shadow-md: 0 4px 12px rgba(100,85,65,0.16); + --shadow-lg: 0 8px 30px rgba(100,85,65,0.2); - --bg-row: #ede7db; - --bg-row-alt: #f0ebe0; - --bg-row-hover: #e5ddd0; - --bg-nested: #f5f0e8; - --bg-accent: color-mix(in srgb, #b8893a 8%, transparent); + --bg-row: #d4ccbd; + --bg-row-alt: #d9d1c3; + --bg-row-hover: #cbc2b2; + --bg-nested: #ddd6c8; + --bg-accent: color-mix(in srgb, #b8893a 10%, transparent); --border-accent: #b8893a; --text-bright: #2c2418; - --text-faint: #b8a898; - --link: #4a7ea8; - --link-hover: #5a8eb8; + --text-faint: #9a8e7e; + --link: #3a6e98; + --link-hover: #4a7ea8; --accent-bar: linear-gradient(90deg, #b8893a, #0d9488); --decision: #ca8a04; --insight: #0d9488;