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;