A knowledge management system built around GDBM storage and the JSONHTL document format. It provides REST, command-line, Python module, and MCP access to the notes database.
See also: Todo list
Core layers:
• Database Layer — GDBM storage with extent attribute handling
• HTTP/MCP Server — FastAPI REST API, MCP transport, OAuth gate, and proxy-facing deployment
• Client Interface — command-line, Python module, and MCP access
• MCP Server and OAuth Access — combined REST/MCP runtime, OAuth dynamic client registration, Codex access, and setup notes
• HTTP/MCP Server — combined server process for REST and MCP
• Database Layer (gdata.py) — GDBM abstraction with JSON handling
• Notes Client (notes_client.py) — CLI and module interface
• Backup System — archive import/export with directory structure preservation
• Test Infrastructure — test suites for protocols and clients
• Infrastructure & Runtime — stunnel path, ports, dynamic IP, REST quick reference
• Troubleshooting — double-encoding, patch failures, connection refused
All documents conform to JSONHTL specification with block elements para, heading, codeblock and inline elements plain text, link, and code.
• HTTP Response Formats — Accept-header content negotiation for /notes/{key} (html, json/jsonhtl+json, yaml, markdown/plain; 406 + Vary)
• nbshot — command-line helper that drives the desktop notes browser's control socket (navigate + off-screen capture)
Current combined deployment uses gdata_mcp_server.py with REST on 127.0.0.1:8020 and MCP on 127.0.0.1:8023 against .agent_notes.gdbm. Public access is proxied through https://www.critchley.biz with OAuth/bearer-token protection for MCP. Older notes may still mention port 8021 or a separate test deployment; verify against the running process before relying on those details.
• JSONHTL document storage with explicit links
• Hierarchical key organisation by convention using /
• REST and MCP access to the same GDBM-backed data
• Command-line and Python client interfaces
• Backup/import/export support
Karpathy's LLM-WIKI.md paper describes an independently-developed architecture with strong parallels to this system: CONTENTS ↔ index.md (one-line summaries, organised by category); MEMORY + TRIGGERS + PROGRAMMING_RULES ↔ CLAUDE.md (schema and agent conventions); notes themselves ↔ wiki/ (LLM-written documents, human reads). Notable gap: the paper's log.md (append-only chronological record) has no equivalent here. The paper's ingest/query/lint primitives also map to how sessions interact with these notes — worth considering as a formal framing for agent operations.
See also: Structured Context Protocol — proposes a phase model (orient/gather/plan/execute/verify/commit) that maps to Karpathy's primitives.