Skip to content

docs: post-v0.34.0 documentation audit + darken Parchment theme #364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CalebisGross merged 1 commit into from
Mar 29, 2026
Merged

docs: post-v0.34.0 documentation audit + darken Parchment theme #364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 58 additions & 13 deletions ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

---

Expand Down Expand Up @@ -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 <token>` header (configure with `mnemonic generate-token`).
Expand All @@ -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)

---

Expand Down Expand Up @@ -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
Expand All @@ -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/
Expand All @@ -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
Expand All @@ -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
Expand Down
9 changes: 6 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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
```
Expand Down
38 changes: 26 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand All @@ -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`):

Expand Down Expand Up @@ -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.

Expand All @@ -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 |
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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)
Expand All @@ -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
```

Expand Down
40 changes: 20 additions & 20 deletions internal/web/static/css/tokens.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down