memrant

The context layer for agent-operated products.

Give your AI agents memory. Log decisions, compile session context, detect stale records, route tasks, enforce specs. One SQLite file. Works offline.

memrant.vercel.app

Install

npm install -g memrant

Quick Start

cd your-project
memrant init --with-specs                 # create ledger + starter spec docs
memrant setup claude-code                 # auto-configure MCP server
memrant log --type decision --content "Chose Express over Fastify — team familiarity"
memrant session start --epic "Auth v2"    # compiled context from previous sessions
memrant recall "API framework choice"     # semantic search across all records
memrant session close --log "Shipped auth flow, added rate limiting"

What It Does

Decision Ledger

Append-only records with vector embeddings. Decisions, framework fixes, spec snapshots — all semantically searchable. Exports to markdown and JSON.

Session Lifecycle

memrant session start compiles everything: last session's log, open TODOs, relevant decisions, framework fixes, spec constraints. The "3-week Monday morning" test — full context without opening a browser tab.

Staleness Detection

Codebase snapshots track file hashes. When a file changes after a decision was logged about it, that record is flagged [stale] in recall and session context.

Model Orchestrator

Three tiers: triage (Haiku), analysis (Sonnet), build (Opus). Each gets tier-appropriate context. Status checks get 500 tokens. Build tasks get the full compiled context. Triage from Telegram.

Spec Governor

Copy audits catch banned phrases. Design system checks catch banned components. Persona tests verify features against named scenarios. memrant lint runs in CI with file:line output.

Commands

| Command | Description | |---------|-------------| | memrant init | Initialise a new project | | memrant init --with-specs | Init with starter spec documents | | memrant setup claude-code | Auto-configure MCP server for Claude Code | | memrant setup codex | Auto-configure MCP server for Codex | | memrant instructions | Output agent instructions for your project | | memrant log | Log a decision, framework fix, or spec snapshot | | memrant recall | Semantic search across all records | | memrant session start | Start a session with compiled context | | memrant session close | Close session with a log entry | | memrant session status | Show active session info | | memrant snapshot | Take a codebase snapshot | | memrant snapshot --diff | Show changes since last snapshot | | memrant ask | Route a question through the model orchestrator | | memrant export | Export ledger to markdown or JSON | | memrant specs | List registered spec documents | | memrant check-copy | Run copy audit against spec | | memrant check-design | Check for banned components | | memrant test-persona | Run persona tests against a feature | | memrant lint | Run all spec checks (CI-friendly) | | memrant serve | Start MCP server |

MCP Server

memrant exposes 6 tools via MCP (stdio transport):

• memrant_log — Log a record
• memrant_recall — Semantic search
• memrant_session_context — Get compiled session context
• memrant_status — Project status
• memrant_check_copy — Copy audit
• memrant_check_design — Design system validation

Auto-configure with memrant setup claude-code or memrant setup codex. Works with any MCP-compatible agent.

Stack

• TypeScript, Node.js (ESM)
• SQLite via better-sqlite3
• Local vector embeddings via @xenova/transformers (all-MiniLM-L6-v2)
• CLI via Commander.js
• MCP server via @modelcontextprotocol/sdk
• 183 tests via vitest

Development

git clone https://github.com/peureka/memrant.git
cd memrant
npm install
npm run build
npm test

Documentation

• docs/SPEC.md — Data model and system behaviours
• docs/PLAN.md — Build plan with epics, stories, and acceptance criteria
• docs/PROJECT_INSTRUCTIONS.md — Product vision and decision framework
• docs/PERSONA_KAI.md — Primary persona

License

MIT