⌬ Lexicon Guard
Local knowledge guardian for AI agents — preferences, code styles, decisions, lessons, and user config, all stored in a local SQLite database.
Lexicon Guard is an MCP (Model Context Protocol) server written in Go that acts as a persistent memory layer for AI coding agents. It captures user preferences, coding style conventions, architectural decisions, technical lessons learned, and user configuration — surfacing them to the agent as discoverable MCP tools.
- Local-first: All data lives in
~/.lexicon/lexicon.db. No cloud, no telemetry.
- Zero CGO: Uses
modernc.org/sqlite, a pure-Go SQLite driver.
- Dual transport: Supports both stdio (default) and HTTP transport.
- Toolbelt layer: Lightweight tool discovery mechanism with categories.
- Engram-compatible: Can optionally sync observations to the Engram memory server.
> 💡 Recommended: Use Lexicon Guard alongside Engram for full-spectrum memory. Engram handles project-level observations; Lexicon Guard adds user-level persistent knowledge (preferences, styles, decisions, lessons). Together they cover everything your agent needs to remember. See Relationship with Engram for details.
Quick Start
Install
# macOS / Linux (recommended)
brew install seinra/lexicon-guard/lexicon-guard
# Windows
winget install Seinra.lexicon-guard
# Cross-platform (from source)
go install github.com/Seinra/lexicon-guard/cmd/lexicon@latest
> Tip: For a real version string instead of dev:
>
> bash > go install -ldflags="-X main.version=v0.1.0" github.com/Seinra/lexicon-guard/cmd/lexicon@latest >
Setup Your Agent
# Install for all detected agents (Pi, VS Code, Cursor, Codex, etc.)
lexicon setup --all
# Or install for specific agents
lexicon setup --agent pi --agent vscode --agent cursor
# List supported agents
lexicon setup --list-agents
| Agent | One-liner |
|---|
| Pi | lexicon setup pi |
| VS Code (Copilot) | lexicon setup vscode |
| Cursor | lexicon setup cursor |
| Codex | lexicon setup codex |
| OpenCode | lexicon setup opencode |
| Gemini CLI | lexicon setup gemini-cli |
| Windsurf | lexicon setup windsurf |
| Claude Code | lexicon setup claude-code |
| Antigravity CLI | lexicon setup antigravity-cli |
| Qwen Code | lexicon setup qwen |
| Kiro IDE | lexicon setup kiro |
| Kilo Code | lexicon setup kilocode |
| Any other MCP client | See Agent Setup |
What lexicon setup does — writes MCP config and instruction files for the chosen agent. After setup, restart your agent and it's ready. No server to start manually.
> Do I need to run lexicon --http or lexicon myself?
>
> For most agents (VS Code, Cursor, Codex, Gemini CLI, Windsurf) — no. Your agent launches lexicon automatically as a short-lived stdio subprocess whenever it starts a session. You never run it manually.
>
> lexicon --http is only needed when you want the REST API or OpenAPI spec available on a port.
No Node.js, no Python, no Docker. One binary, one SQLite file.
Features
- 16 MCP tools covering preferences, coding styles, design decisions, lessons learned, context, web requests, and Engram sync — all auto-discoverable by the agent.
- Toolbelt discovery layer — agent explores available tools without loading all schemas at once (tools loaded on demand).
- Cross-platform installer —
lexicon setup works on macOS, Linux, and Windows, supporting 12 agents.
- Dual transport — stdio (default, automatic) and HTTP (opt-in with
--http).
- REST API — Create and read operations over HTTP at
/api/v1/*, plus OpenAPI 3.1 spec.
- FTS5 full-text search over lessons learned.
- Engram sync — push, pull, or bidirectional sync with the Engram memory server. Also serves as a failover mechanism: if Engram is down, save to Lexicon Guard's local DB and
sync push when it recovers.
- Engram proxy — direct
lexicon_mem_search / lexicon_mem_get_observation with a 3s timeout. Returns a degraded-mode response (not an error) when Engram is unreachable, so the agent knows to use local tools instead.
- Rate limiting — 100 req/min per IP on REST routes.
- Audit logging — every write operation is logged internally.
- Graceful shutdown — handles SIGINT/SIGTERM.
Lexicon Guard exposes 16 MCP tools that the agent uses automatically. The Toolbelt is a lightweight discovery layer that lets the agent explore what tools exist without loading all their schemas — loads on demand only what it needs.
| Tool | Purpose |
|---|
lexicon_preference_set | Create or update a user preference |
lexicon_preference_get | Get a user preference by key |
lexicon_preference_list | List preferences, optionally filtered by category |
lexicon_style_set | Set coding style for a language |
lexicon_style_get | Get coding style for a language |
lexicon_decision_save | Save an architecture or design decision |
lexicon_decision_list | List recent decisions |
lexicon_context_set | Create or update a context entry (key/value with scope: global/project/session) |
lexicon_context_get | Get context entries, optionally filtered by scope |
lexicon_lesson_save | Save a technical lesson learned |
lexicon_lesson_search | Search lessons by text or tags (FTS5 full-text search) |
lexicon_lesson_list | List recent lessons |
lexicon_webrequest | Make HTTP/HTTPS requests (API docs, etc.) |
lexicon_sync_engram | Sync observations with an Engram server (push/pull/both) |
lexicon_mem_search | Search Engram observations directly (proxy, 3s timeout) |
lexicon_mem_get_observation | Get an Engram observation by ID directly (proxy) |
The Toolbelt prevents overwhelming the agent with 16 full schemas at once:
| Tool | Description |
|---|
toolbelt/list | All tools with name, description, category (no inputSchema) |
toolbelt/schema | Full inputSchema for a specific tool (on-demand) |
toolbelt/categories | Available categories |
Categories: preferences, styles, decisions, lessons, context, system, engram.
How it works: Agent calls toolbelt/list → sees categories → toolbelt/categories → filters → toolbelt/schema for specific tool → calls the tool.
The agent calls these tools automatically when relevant — you don't invoke them manually.
Relationship with Engram
Lexicon Guard is complementary to Engram, not a replacement.
| Dimension | Engram | Lexicon Guard |
|---|
| Scope | Project-level memory (observations per project) | User-level memory (global preferences, styles, decisions, lessons) |
| Focus | General-purpose observation store | Structured knowledge domains with typed schemas |
| Transport | HTTP server | stdio (default) + HTTP (optional) |
| Search | Basic query | FTS5 full-text search over lessons + structured queries |
| Setup | Run as a standalone HTTP service | Agent launches automatically via MCP config |
| Sync | — | Can push/pull observations to/from Engram |
Use Engram for project-level ephemeral observations. Use Lexicon Guard for user-level persistent knowledge that survives across projects. Together they cover the full memory spectrum.
Lexicon Guard can sync with Engram via lexicon_sync_engram (push, pull, or bidirectional), and also provides lexicon_mem_search / lexicon_mem_get_observation as proxy tools with a longer timeout for when the agent's health check is too strict. This sync also acts as a failover mechanism: if Engram is unreachable, save data locally via lexicon_* tools and sync push when Engram recovers.
Documentation
| Doc | Description |
|---|
| Installation | All install methods + platform support |
| Agent Setup | Per-agent configuration + Memory Protocol |
| Architecture | How it works, REST endpoints, OpenAPI spec, project structure |
| Usage Instructions | MCP tool reference, sync configuration + conflict resolution |
Architecture
┌────────────────────┐ ┌────────────────────────┐
│ Agent / Client │ │ HTTP (optional) │
│ (Claude, Cline, │ │ POST /mcp/server │
│ custom MCP host) │ │ + REST API │
└────────┬───────────┘ └───────────┬────────────┘
│ stdio (JSON-RPC 2.0) │ HTTP
▼ ▼
┌────────────────────┐ ┌────────────────────────┐
│ StdioServer │ │ MCPServer │
│ (internal/server/)│ │ (internal/server/) │
└────────┬───────────┘ └───────────┬────────────┘
│ │
└──────────────┬───────────────┘
▼
┌────────────────────────┐
│ ServerManager │
│ (internal/tools/) │
│ Business logic + │
│ audit logging │
└────────────┬───────────┘
▼
┌────────────────────────┐
│ Store Interface │
│ (internal/db/) │
│ SQLite persistence │
└────────────────────────┘
Layers:
- Transport (
internal/server/) — StdioServer + MCPServer handle JSON-RPC 2.0
- Business logic (
internal/tools/) — ServerManager, handlers, validation, audit
- Persistence (
internal/db/) — Store interface backed by SQLite (pure Go, no CGO)
- Engram sync (
internal/engram/) — Optional client to sync observations
Project Structure
cmd/lexicon/
├── main.go # CLI entry, flag parsing, server selection
├── setup.go # `lexicon setup` command
├── uninstall.go # `lexicon uninstall` command
internal/
├── db/ # SQLite persistence, types, CRUD
├── engram/ # Engram HTTP client, mapping, config
├── server/ # Stdio/HTTP transport, REST, toolbelt
├── testutil/ # Mock store for tests
└── tools/ # Business logic, handlers, schema
Configuration
Zero config by default. Database auto-created at ~/.lexicon/lexicon.db.
CLI Flags
| Flag | Default | Description |
|---|
--http | "" | HTTP listen address (e.g. :50051). Empty = stdio-only. |
Engram Sync (Environment Variables)
See Usage Instructions — Engram Sync Details for full reference.
Database
- Engine: SQLite via
modernc.org/sqlite (pure Go, no CGO)
- Location:
~/.lexicon/lexicon.db
- Tables:
preferences, styles, decisions, context, lessons_learned, audit_logs
- Schema: Auto-created on first run — no migrations needed
Acknowledgments
Built with gratitude to the Gentleman Programming community for Engram — the peer memory system Lexicon Guard was designed to complement — and to the Gentle-AI ecosystem that made development a joy.
Special thanks to The Gentleman for creating and maintaining Engram, whose design inspired Lexicon Guard's sync capabilities and whose existence as a complementary project shaped its architecture from day one.
Contributing
Contributions welcome! Open an issue or submit a PR on GitHub.
License
MIT License — see LICENSE for details.