Lex

Local memory and policy context for AI coding agents.

Don't trust the README. Ask your agent.

"Would repo-local memory and policy context help you work in this codebase with fewer repeated explanations, fewer forgotten constraints, and better handoffs between sessions?"

If the answer is yes, Lex is the layer that gives your agent somewhere durable to put that context.

60-second test | Quick Start | Agent Integration | Documentation | API Reference | Contributing

What Lex gives your agent

Lex is repo-local memory and policy context for AI coding agents. It stores structured work snapshots, recalls relevant prior context, and connects that context to repository policy when a policy file is available.

Agents get:

• Durable Frames for reference points, summaries, blockers, next actions, branches, tickets, and module scope
• Policy-aware recall that can surface nearby module context instead of asking the human to restate it
• Structured CLI and MCP responses that are easier for tools to parse
• Stable tool names and explicit error codes for recovery
• Repo-local context stored in SQLite and repository files, not a cloud memory service
• CLI, MCP, and TypeScript API surfaces for different agent runtimes

Humans do not need to understand the whole framework before adoption. The first useful question is simply whether your agent keeps asking you to repeat context the repository could remember.

The 60-second test

Paste this into Copilot, Claude, Cursor, or another coding agent while it has access to your repository:

Look at this repository. Would a repo-local memory and policy layer help you avoid repeated context setup, forgotten project constraints, or poor handoffs? If yes, where would Lex help first?

A useful answer usually names a recurring handoff problem: interrupted feature work, architecture-sensitive modules, policy constraints, release workflows, or places where agents repeatedly need the same explanation.

How it works

Frames: work memory

Frames capture meaningful moments in a development workflow:

lex remember \
  --reference-point "Implementing user authentication" \
  --summary "Added JWT validation to API middleware" \
  --next "Wire up password reset flow" \
  --modules "services/auth,api/middleware" \
  --blockers "Need PermissionService access - forbidden edge in policy" \
  --jira "AUTH-123"

Frames are meant for durable agent context: what changed, what remains, where it happened, and what should be respected next time.

Learn more about Frames

Recall: prior context on demand

Later, an agent can recall relevant context by topic:

lex recall "authentication"
# Returns matching context, blockers, next action, and relevant module neighborhood.

Recall is the everyday adoption path: before changing code, ask Lex what prior work, blockers, and nearby boundaries matter.

Atlas: nearby repository context

When a Frame is recalled, Lex can provide an Atlas Frame: the touched modules plus their immediate neighborhood, including dependencies, dependents, and permissions.

This fold-radius approach keeps recall focused on nearby repository context instead of flooding the agent with the whole codebase.

Learn more about Atlas

Policy: architectural boundaries

Lex policy files define repository boundaries as code:

{
  "modules": {
    "ui/components": {
      "owns": ["src/ui/components/**"],
      "mayCall": ["services/auth", "ui/shared"],
      "forbidden": [
        {
          "target": "database/queries",
          "reason": "UI must not access database directly. Use API layer."
        }
      ]
    }
  }
}

Enforce in CI:

lex check merged-facts.json
# Violation: ui/components -> database/queries (forbidden edge)
# Reason: UI must not access database directly. Use API layer.

Learn more about Policy

Instructions: project assistant guidance

Lex can project canonical assistant instructions into host-specific files:

# Your canonical instructions live in one place
.smartergpt/instructions/lex.md

# Project them to host-specific files
lex instructions generate
# Creates: .github/copilot-instructions.md, .cursorrules

The marker system preserves human content while keeping generated agent guidance deterministic.

Learn more about Instructions

Quick Start

Installation

# Install globally (recommended)
npm install -g @smartergpt/lex

# Or locally in your project
npm install @smartergpt/lex

Requires Node.js 20+ and currently supports Node.js 20 through 24, matching the package engine range.

WSL users should use a native WSL install on PATH, not Windows npm shims or npm's _npx cache. See WSL Native Lex Install for the recommended user-local install, checkout symlink bridge, and native SQLite build requirements.

Lex supports structured output (--json), recoverable errors (AXError), and Frame Schema v3 for orchestrator integration. Commands provide both human-readable and machine-parseable output where supported.

Initialize

# Zero-to-value initialization
npx @smartergpt/lex init --yes
# Auto-detects project type (Node.js, Python, Rust, Go, etc.)
# Creates:
#   .smartergpt/ - Workspace with prompts, policy, and instructions
#   .github/copilot-instructions.md - IDE instructions with LEX markers
#   .cursorrules - Cursor IDE instructions (if Cursor detected)
#   lex.yaml - Configuration with sensible defaults
#   .smartergpt/lex/memory.db - SQLite database (initialized on first use)
# Shows MCP server configuration guidance
# Idempotent: safe to run multiple times

# Interactive mode (prompts for first Frame)
lex init --interactive

# Generate seed policy from directory structure
lex init --policy
# Scans src/ for TypeScript/JavaScript modules
# Generates .smartergpt/lex/lexmap.policy.json with discovered modules
# Example: src/memory/store/ -> memory/store module with src/memory/store/** match pattern

# Force reinitialize (overwrite existing files)
lex init --force

During init, Lex detects common project types, creates IDE instruction files with LEX markers, writes lex.yaml, initializes .smartergpt/lex/memory.db, and prints MCP server configuration guidance.

Capture the first useful Frame

lex remember \
  --reference-point "Refactoring payment processing" \
  --summary "Extracted validation logic to PaymentValidator" \
  --next "Add unit tests for edge cases" \
  --modules "services/payment"

Recall it later

lex recall "payment"
# Shows your context, blockers, and architectural neighborhood.

Full Quick Start Guide

MCP setup

Use Lex with any MCP-compatible AI assistant, including VS Code and Claude Desktop:

# Install the MCP wrapper
npm install -g @smartergpt/lex-mcp

# Or run directly
npx @smartergpt/lex-mcp

VS Code configuration (.vscode/mcp.json):

{
  "servers": {
    "lex": {
      "command": "npx",
      "args": ["@smartergpt/lex-mcp"],
      "env": {
        "LEX_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Claude Desktop configuration:

{
  "mcpServers": {
    "lex": {
      "command": "npx",
      "args": ["@smartergpt/lex-mcp"]
    }
  }
}

MCP Server Documentation

Agent Integration

Lex is designed to be consumed by agents and tools, not only read by humans.

• CLI: lex remember, lex recall, lex check, lex timeline, lex instructions, and database maintenance commands are scriptable entry points.
• MCP: @smartergpt/lex-mcp exposes Lex through Model Context Protocol for assistants that support MCP.
• Structured JSON: supported commands can emit machine-parseable output for orchestration and recovery.
• Recoverable errors: AXError includes code, message, context, and nextActions[] fields.
• Stable tool names: MCP tools have explicit names rather than relying on prose prompts.

The MCP server exposes 14 tools for episodic memory, policy validation, and architectural analysis:

• frame_create, frame_search, frame_get, frame_list, frame_validate
• policy_check, timeline_show, atlas_analyze
• system_introspect, help, hints_get
• contradictions_scan, db_stats, turncost_calculate

MCP is an adapter surface. Lex itself is the memory and policy core.

Where agents use Lex

• Before editing: recall prior work, blockers, and relevant module boundaries.
• During handoff: store the current branch, next action, and unresolved constraints.
• During review: check policy facts against repository boundaries.
• During onboarding: inspect focused Atlas context instead of asking for a full codebase tour.
• During orchestration: emit structured output for runners and other tools.

Dogfooding examples are available in examples/dogfood/. They show real Frames from building Lex with Lex.

Human/operator view

Humans see a local, inspectable record instead of an opaque assistant memory:

• Frames are stored in SQLite at .smartergpt/lex/memory.db by default.
• Policy files live in the repository and can be reviewed in code review.
• NDJSON logs are written to .smartergpt/lex/logs/lex.log.ndjson with structured fields such as timestamp, level, operation, duration_ms, metadata, and error.
• Policy checks can run in CI with lex check merged-facts.json.
• Database maintenance commands support backups, rotation, and vacuuming.

# Create a timestamped backup (memory-20251123.sqlite)
lex db backup --rotate 7
# Keeps last 7 backups, stored in .smartergpt/lex/backups/

# Optimize database (rebuild and compact)
lex db vacuum

# Set backup retention via environment variable
export LEX_BACKUP_RETENTION=14  # Keep 14 most recent backups

Logs rotate automatically at 100MB and are silent in test mode unless LEX_LOG_NDJSON=1 is set.

Lex is not

• Lex is not a cloud memory service.
• Lex is not a chatbot.
• Lex is not a replacement for tests, code review, or CI.
• Lex is not an MCP-only project.
• Lex is not AXF, LexRunner, or LexSona.

Relationship to AXF, LexRunner, and LexSona

Lex is the memory and policy core.

• Lex remembers and explains project context through Frames, recall, Atlas, policy, instructions, and structured output.
• AXF is the inspectable capability/control-plane layer for agent-operable tooling: manifests, routing, execution surfaces, scaffolding, and lifecycle gates.
• LexRunner composes work over capabilities and runpaths, including parallel PR workflows and merge planning.
• LexSona consumes the public behavioral memory socket (@smartergpt/lex/lexsona) for persona and guardrail integration. Lex core remains persona-agnostic.

A useful mental model: Lex remembers and explains context; AXF exposes bounded capabilities; LexRunner coordinates work; LexSona derives behavioral constraints.

Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Installation and Setup - Detailed installation guide
• Core Concepts - Understanding Frames, Atlas, and Policy

Guides

• Frame Recall Guide - Using Frames for reference-point recall
• Code Atlas Guide - Spatial memory and architectural context
• Policy Enforcement - Setting up architectural boundaries
• Instructions Generation - Sync AI instructions across IDEs
• CLI Reference - Command-line usage and output modes
• MCP Server Documentation - Using Lex with Model Context Protocol
• OAuth2/JWT Authentication - Multi-user authentication setup

Security

• Security Policy - Security posture and best practices
• OAuth2/JWT Guide - Authentication and user isolation

Advanced

• Architecture - System layers and module context
• Architecture Loop - How Frames, Atlas, and Policy interact
• API Reference - TypeScript API documentation
• Limitations - Known constraints and future work
• FAQ - Common questions

Development

• Contributing Guide - How to contribute
• Release Process - Versioning and publishing
• ADRs - Architectural decision records

API Reference

Lex provides multiple entry points for agents, tools, and application code:

Core API

import { saveFrame, searchFrames, getDb, closeDb } from '@smartergpt/lex';

const db = getDb(); // Uses .smartergpt/lex/memory.db

await saveFrame(db, {
  referencePoint: 'authentication flow',
  summaryCaption: 'Added password validation',
  statusSnapshot: { nextAction: 'Wire up permission check' },
  moduleScope: ['services/auth', 'services/password'],
  branch: 'feature/auth',
  jira: 'AUTH-123'
});

const results = await searchFrames(db, { referencePoint: 'authentication' });
closeDb(db);

Subpath exports

Full API Documentation

Project status

Current Version: 2.7.1 (Changelog)

Current Lex releases include structured output, recoverable errors, and Frame Schema v3 for agent and orchestrator integration.

Commonly used for:

• Personal projects and local dev tools
• Private MCP servers
• CI/CD policy enforcement
• LexRunner and other orchestrator integrations
• Documented multi-user authentication and encrypted database setup paths for deployments that need them

Current capability highlights:

• Structured output contract (v0.1): machine-parseable output, recoverable errors, and recall-focused events (AX Contract)
• Frame Schema v3: runner fields such as runId, planHash, and toolCalls for orchestration (Schema Docs)
• AXError Schema: structured errors with code, message, context, and nextActions[] for programmatic recovery
• CLI JSON Output: lex remember --json and lex timeline --json with machine-parseable event streams
• Instructions Management: lex instructions CLI for syncing AI instructions across IDEs
• LexSona Socket: behavioral memory API (recordCorrection/getRules) exported via @smartergpt/lex/lexsona
• Performance: cached policy module ID lookups for O(1) resolution

Lex 2.0.0 introduced the public behavioral memory socket (@smartergpt/lex/lexsona) for persona-based workflows. LexSona is a separate private package that consumes this socket to enable offline-capable persona modes. Lex itself is persona-agnostic.

See the changelog for release history and version-specific notes.

Contributing

Contributions are welcome.

1. Read the Contributing Guide and Development Setup.
2. Pick an issue from good first issues or help wanted.
3. Submit a PR with tests and documentation where they apply.

Follow the repo's commit conventions and signing requirements documented in the contributing guide.

Related projects

• LexRunner - Orchestration for parallel PR workflows.
• LexSona - Behavioral persona engine that consumes Lex's public behavioral memory socket.
• AXF - Capability/control-plane layer for agent-operable tooling.

License

MIT License. See LICENSE for full text.

Links

• Documentation
• Examples
• npm Package
• Issues
• Discussions

Advanced topics

TypeScript build system

Lex uses TypeScript project references for deterministic, incremental builds:

npm run build      # Compile with project references
npm run clean      # Clean build artifacts
npm run typecheck  # Type-check without emitting

Why NodeNext module resolution?

• Source uses .ts files with .js import extensions.
• TypeScript resolves imports during compilation.
• Emitted .js files work correctly in Node.js ESM.
• There is no confusion between source and build artifacts.

Build System Details

Local CI with Docker

Run CI checks locally without touching GitHub:

npm run local-ci          # Run full CI suite locally
npm run local-ci:nonet    # Run without network access

This uses ci.Dockerfile for local parity with CI checks.

Multi-language policy scanning

While TypeScript scanning is built in, Python and PHP scanners are available as examples:

# Scan Python codebase
python examples/scanners/python/scan.py src/ > python-facts.json

# Scan PHP codebase
php examples/scanners/php/scan.php src/ > php-facts.json

# Merge with TypeScript facts
lex merge ts-facts.json python-facts.json > merged-facts.json

# Check policy
lex check merged-facts.json

Security note: external scanners execute arbitrary code. Review before use.

Scanner Documentation

Customizing prompts and schemas

Lex uses a precedence chain for configuration:

1. Environment: LEX_CANON_DIR=/custom/canon (highest)
2. Local overlay: .smartergpt/prompts/
3. Package defaults: prompts/ (lowest)

# Customize locally
cp prompts/remember.md .smartergpt/prompts/
vim .smartergpt/prompts/remember.md

# Or use custom directory
LEX_CANON_DIR=/my/custom/canon lex remember ...

Environment variables

Database encryption

Protect your Frame data with SQLCipher encryption:

# Enable encryption for new databases
export LEX_DB_KEY="your-strong-passphrase-here"
lex remember --reference-point "work" --summary "Encrypted!"

# Migrate existing database
lex db encrypt --verify

# Production mode requires encryption
export NODE_ENV="production"
export LEX_DB_KEY="production-passphrase"

Key features:

• AES-256 encryption at rest
• PBKDF2 key derivation (64K iterations)
• Mandatory in production (NODE_ENV=production)
• Migration tool with integrity verification

Security Guide

Environment Configuration

Development

Prerequisites

• Node.js v20+ LTS, with CI coverage on Node.js 20, 22, and 24
• npm v10+
• Git for branch detection

Local setup

# Clone repository
git clone https://github.com/Guffawaffle/lex.git
cd lex

# Install dependencies
npm ci

# Build
npm run build

# Run tests
npm test

# Local CI (full suite)
npm run local-ci

Project structure

lex/
|-- src/                     # TypeScript source (no .js files)
|   |-- memory/              # Frame storage and MCP server
|   |-- policy/              # Policy enforcement and scanners
|   |-- shared/              # Shared utilities and types
|   `-- index.ts             # Main entry point
|-- dist/                    # Build output (gitignored)
|-- canon/                   # Canonical prompts and schemas
|-- docs/                    # Documentation
|-- examples/                # Usage examples and optional scanners
|-- test/                    # Test suite
`-- .smartergpt/             # Local workspace (gitignored)

Running tests

npm test                     # Run all tests (excludes git tests)
npm run test:coverage       # With coverage report
npm run test:watch          # Watch mode
npm run test:git            # Git integration tests (requires non-interactive signing)

Git tests are quarantined due to mandatory GPG signing in this environment. See test/README.md for details.

Code quality

npm run lint                # ESLint checks
npm run format              # Prettier formatting
npm run typecheck           # TypeScript validation

Contributing Guide