v2.0.0 on npm • MIT-licensed • Node ≥20

Lex: Policy-Aware Work Continuity

Lex is the open-source memory + policy engine in the smartergpt stack. It combines architecture policy-as-code with episodic memory (Frames) and Atlas Frames so you can ask "why is this blocked?" and get receipts from timestamped sessions, not vibes.

Transport: MCP stdio • Storage: Local SQLite • Telemetry: None

npm install @smartergpt/lex View on GitHub The 2.0.0 Story

What is Lex?

🧠 Frames

Timestamped work session snapshots with summary, blockers, next action, and module_scope.

Stored locally in SQLite. Indexed by the same module vocabulary used in policy. Designed to be small, explicit, and agent-friendly.

🗺️ Atlas Frames

Fold-radius neighborhoods (default 1) around touched modules to keep context precise and small.

When you recall a Frame, you can also recall its neighboring modules—just enough context, not the whole repo.

🔒 Policy

Machine-readable boundaries in lexmap.policy.json: ownership, allowed/forbidden edges, flags, permissions.

Lex surfaces policy violations as first-class data in Frames and CLI output.

Contracts: lexmap.policy.json + lex.yaml

📜 lexmap.policy.json

Describes architectural boundaries: which modules exist, who owns them, what edges are allowed or forbidden.

📋 lex.yaml

Describes workflows and expectations: what kinds of work exist in this repo, what inputs they expect, and which policies apply.

Learn about lex.yaml →

🔗 Contract Surface

Together they form the contract surface that agents, CI, and runners consume. lex.yaml is intent-level—it does not describe how any runner implements orchestration.

Lex is the part that knows what you said is allowed, what actually happened, and why something is blocked. Anyone can build an executor that consumes lex.yaml; LexRunner just happens to be the one we are building first.

What's in v2.0.0 (AX‑Native)

Lex 2.0.0 is the AX‑native release that matures agent experience guarantees: structured AX errors, Frame Schema v3, CLI improvements, and a behavioral socket for LexSona integration.

📦 Stable Contract Surfaces

Frames, Atlas Frames, lexmap.policy.json, and lex.yaml form a stable, documented surface for agents and runners.

🔧 CLI & MCP Predictability

Commands like lex remember, lex recall, and lex check are shaped for automation: JSON output, schema-checked payloads, and consistent status fields.

🎯 Policy + Memory Alignment

Violations, ownership, and module IDs line up across policy files and Frames, so answers always come with receipts.

📸 Image Support

Attach images to Frames (base64-encoded with MIME type). Uses Sharp for image processing.

🗄️ Local SQLite

Local-first persistence with better-sqlite3. No cloud dependencies, no telemetry. Full control over your data.

📋 JSON Schemas

Included schemas: profile.schema.json, feature-spec-v0.json, cli-output.v1.schema.json for validation and tooling integration.

From 0.4.6-alpha to 1.0.0

The Lex / LexRunner Boundary

The surprising part of Lex 1.0.0 is not the version number; it is how quickly we moved once we stopped treating Lex as "just memory" and started treating it as the contractual backbone of the stack.

LexRunner forced the question: what does Lex absolutely owe to any runner, and what must remain private?
Clear responsibilities: Lex owns Frames (episodic memory), policy (lexmap.policy.json), and contracts (lex.yaml).
Velocity spiked: with the contracts in place, we could iterate on Lex, LexRunner, and orchestration prompts in parallel.
GitHub throttling: at one point, GitHub literally restricted our activity—evidence that the architecture and low-token strategies are real, and a reminder to treat hosted agents and CI as shared infrastructure.

We do not present the GitHub throttling as "look how hardcore we are." We present it as evidence that the architecture works, and as a reminder that responsible velocity means respecting platform limits and leaning on coding agents intelligently, not just pushing harder.

Read the full 2.0.0 story →

Why it works

Shared Vocabulary = Receipts

Frames use the same module IDs as policy and the same workflow names as lex.yaml. Assistants and tools can cite which policy rule was violated, which Frame observed it, and which workflow it is blocking.

That's explainable recall with receipts, not guesses.

Local-First, Agent-Friendly

Local SQLite. No cloud dependency. MCP stdio transport so agents can talk to Lex like any other tool. No telemetry; your history stays on your machine.

Status & Install

Status

v2.0.0 released! Available on npm as @smartergpt/lex. AX guarantees are stable and documented — see AX Contract & Frame Schema v3. Lex now exports a LexSona behavioral socket for persona integrations. Recent private work (LexSona 0.2.0) adds offline-capable persona modes that can run with limited memory availability; standalone LexSona packages and deeper integrations remain controlled-access.

Node ≥20 • MIT Licensed

Install

Install globally for CLI access or as a dependency for programmatic use.

# Global install (CLI)
npm install -g @smartergpt/lex

# Or as a project dependency
npm install @smartergpt/lex

After installation, run npx lex init to set up your workspace, then use lex remember, lex recall, lex check, lex instructions and more. For AX details see AX Contract v0.1.

See the GitHub repo for full documentation and examples.