Interface & CLI Layer
Implements fat binary routing, Smart TTY detection, and CLI subcommands to expose shared memory states directly to terminal users.
Architecture
[AI Agent / IDE] [Human / Terminal]
│ │
(JSON-RPC 2.0 via STDIO) (Flag Commands)
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ MCP Transport Layer │ │ CLI Dispatcher │
└──────────┬───────────┘ └──────────┬───────────┘
│ │
(Strong Types) (Shared State)
│ │
└─────────────┬───────────────┘
▼
┌─────────────────────────┐
│ Shared Service Layer │
└────────────┬────────────┘
│
(Validation)
▼
┌─────────────────┐
│ Storage Engine │
└────────┬────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
(WAL Persistence) (Full-Text Search) (Telemetry)
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ SQLite LTM DB │ │ FTS5 Virtual Tab │ │ DuckDB Analytics │
└──────────────────┘ └──────────────────┘ └──────────────────┘
Core Components & Logic
MCP Transport Layer
Handles Model Context Protocol registrations and maps incoming JSON-RPC 2.0 messages onto typed service boundaries.
Memory Service
Orchestrates retrieval and maintenance logic, routing queries between basic scans and the FTS5 virtual table.
Persistence & Telemetry
Manages local SQLite WAL storage, automated FTS5 index updates, and DuckDB analytical query runners.
Validation & Resiliency Testing
Reproducibility
Development environment bootstrapping using Nix (shell.nix) and reproducible project builds via Makefile automation.
Automated Verification
Continuous validation verified via local Go benchmarking suite (make bench) and standard unit testing.
Telemetry Pipeline
Granular cost, latency, and knowledge ROI tracking compiled automatically with the embedded DuckDB query runner.
Reach
Humble Pivots
FTS5 Virtual Table for Search
Pivoted from basic SQL LIKE queries to SQLite FTS5 index for O(log n) keyword search performance on larger datasets.
ID-based Deletion Confirmation
Introduced surrogate ID confirmation workflows to prevent unintended mass-deletion of semantic context during agent updates.
Objective Clarity
Deterministic, local memory server providing sub-millisecond context retrieval within standard resource budgets.
Verifiable Outputs
goos: linux goarch: amd64 pkg: echo/internal/service cpu: Intel(R) Core(TM) i7-14650HX BenchmarkRecallMemory-24 9771 119078 ns/op 11887 B/op 251 allocs/op BenchmarkSearchMemories-24 1708 672182 ns/op 98352 B/op 1852 allocs/op BenchmarkStoreMemory-24 8908 148335 ns/op 504 B/op 14 allocs/op BenchmarkDeleteMemory-24 12205 109900 ns/op 216 B/op 7 allocs/op PASS ok echo/internal/service 10.967s
=== RUN TestGetDefaultDataDir === RUN TestGetDefaultDataDir/XDG_DATA_HOME_set === RUN TestGetDefaultDataDir/XDG_DATA_HOME_empty --- PASS: TestGetDefaultDataDir (0.00s) === RUN TestGetDefaultDBPath --- PASS: TestGetDefaultDBPath (0.00s) === RUN TestInitDB 2026/06/23 09:26:12 Database initialized at: test_init.db === RUN TestInitDB/CheckTableExistence === RUN TestInitDB/CheckTableExistence/memories === RUN TestInitDB/CheckPragmas === RUN TestInitDB/CheckPragmas/journal_mode === RUN TestInitDB/InvalidPath === RUN TestInitDB/MigrationError --- PASS: TestInitDB (0.01s) PASS ok echo/internal/db (cached) === RUN TestNewServer 2026/06/23 09:27:31 Database initialized at: test_mcp_server.db === RUN TestNewServer/VerifyToolMetadata === RUN TestNewServer/TestToolHandlers_TableDriven === RUN TestNewServer/TestToolHandlers_TableDriven/store_memory_success === RUN TestNewServer/TestToolHandlers_TableDriven/store_memory_missing_content === RUN TestNewServer/TestToolHandlers_TableDriven/recall_memory_success === RUN TestNewServer/TestToolHandlers_TableDriven/recall_memory_missing_keys === RUN TestNewServer/TestToolHandlers_TableDriven/search_memories_success === RUN TestNewServer/TestToolHandlers_TableDriven/search_memories_missing_query === RUN TestNewServer/TestToolHandlers_TableDriven/update_memory_success === RUN TestNewServer/TestToolHandlers_TableDriven/update_memory_invalid_id === RUN TestNewServer/TestToolHandlers_TableDriven/update_memory_missing_content === RUN TestNewServer/TestToolHandlers_TableDriven/search_for_deletion_success === RUN TestNewServer/TestToolHandlers_TableDriven/search_for_deletion_no_match === RUN TestNewServer/TestToolHandlers_TableDriven/search_for_deletion_missing_query === RUN TestNewServer/TestToolHandlers_TableDriven/delete_memory_success === RUN TestNewServer/TestToolHandlers_TableDriven/delete_memory_invalid_id === RUN TestNewServer/TestToolHandlers_TableDriven/get_analytics_success --- PASS: TestNewServer (0.03s) PASS ok echo/internal/mcp (cached)