Lex
Lex remembers the work, not the conversation.
Your agent can read the code. Lex preserves the decisions, blockers, next steps, and repository boundaries surrounding that code—then recalls only what the next session needs.
Local-first. Inspectable. No transcript dump.
See the core loop · Should I use Lex? · Five-minute pilot · Agent evaluation · Documentation
The problem Lex solves
A coding agent can inspect the repository in front of it. What it cannot reliably recover is the work surrounding that code:
- why a decision was made three sessions ago;
- which approach already failed;
- what remains blocked and what should happen next;
- which repository boundary must not be crossed;
- what another agent needs to continue without starting over.
Lex preserves that continuity as deliberate, high-signal Frames.
A Frame is a deliberate handoff, not continuous surveillance. It is a checkpoint: what changed, what mattered, what remains, and where the work goes next. Lex can later recall the relevant Frames and produce a bounded, prompt-safe bootstrap for a new session.
Work happens → Lex remembers what mattered → the next session continues
Start with remember, recall, and context. SQLite is the local default. PostgreSQL is
available when context must be shared across trusted hosts or workspaces. Everything else is
optional.
Remember → recall → continue
lex remember \
--summary "Kept authentication token validation in API middleware" \
--next "Add the service grant and rerun tests" \
--modules unscoped \
--blockers "Missing PermissionService grant"
lex recall "authentication"
lex context "authentication" --max-tokens 500
That is the core loop:
rememberwrites one deliberate work checkpoint;recallretrieves it when the topic becomes relevant again;contextturns matching Frames into a bounded, read-only bootstrap for an agent.
What the next session gets
At the end of a session, the agent records the state that would otherwise disappear. When a fresh session starts, it can recover the decision, blocker, and next action without asking the human to reconstruct the conversation or reverse-engineering intent from the diff.
Decision: token validation belongs in API middleware
Blocker: the service grant is still missing
Next: add the grant and rerun the authentication tests
The value is not that Lex stored a record. The value is that the next session can continue.
Should I use Lex?
Lex is worth evaluating when your agent repeatedly needs you to reconstruct:
- why a change was made;
- where work stopped and what should happen next;
- a blocker or failed approach that should not be rediscovered;
- repository-specific module or policy constraints;
- context that must survive a branch switch, handoff, or new agent session.
Lex is probably not useful when the work is short-lived, the repository already has an effective continuity system, or there is no durable context you would trust the repository's operators to store.
Ask your agent
The evaluation is intentionally read-only. Paste this into an agent that can inspect your repository:
Read https://github.com/Guffawaffle/lex/blob/main/docs/agent-evaluation.md and evaluate this
repository against it. Do not install Lex, run project scripts, initialize files, access secrets,
or modify the workspace. Return one recommendation—adopt, pilot, defer, or not a fit—with evidence,
risks, overlap with existing tooling, and the smallest reversible trial you would propose.
The complete rubric and local-file version are in Agent Evaluation.
Five-minute pilot
Ready to test the claim? Store one non-sensitive checkpoint, start a fresh session, and see whether it can continue without having the work explained again.
Requires Node.js 24 or newer. Lex does not impose an unproven upper bound. Existing users should follow the Lex 4.4 migration and recovery guide and verify the bundled SQLite binary. Lex 4.4.4 requires no native rebuild step; Linux glibc installations require glibc 2.35 or newer.
This approved pilot writes one Frame to the local SQLite store under .smartergpt/lex/. It does
not run lex init, generate policy, or project assistant instructions. Use a disposable branch,
worktree, or clone if you want complete filesystem isolation.
1. Store one real checkpoint
LEX_STORE=sqlite npx @smartergpt/lex remember \
--reference-point "Lex pilot" \
--summary "Evaluating whether durable agent handoffs help this repository" \
--next "Recall this checkpoint in a new session" \
--modules unscoped
LEX_STORE=sqlite prevents existing PostgreSQL configuration from redirecting the pilot into a
shared store.
2. Start fresh, then recover the work
LEX_STORE=sqlite npx @smartergpt/lex recall "Lex pilot"
LEX_STORE=sqlite npx @smartergpt/lex context "Lex pilot" --max-tokens 500
Use that recalled or bounded output in the fresh session and see whether it prevents you from repeating useful context. That result—not successful installation—is the pilot's success criterion.
Review the validation-only step, exact filesystem effects, and rollback guidance
Make checkpoints useful
Good Frames are sparse and specific. Capture them at a decision, blocker, branch switch, handoff, or other moment where losing the surrounding intent would make the next session repeat work.
lex remember \
--reference-point "Authentication refresh" \
--summary "Moved token validation into API middleware" \
--next "Add password-reset coverage" \
--modules "services/auth,api/middleware" \
--blockers "Need PermissionService access"
Capture what changed, make --next actionable, name blockers explicitly, and use the narrowest
honest module scope. Do not capture every edit or tool call.
When repository policy exists, Lex can infer module scope from current evidence:
lex remember \
--summary "Finished context wiring" \
--next "Run validation" \
--modules auto
Use --modules unscoped when the repository does not yet have a useful module ontology. Policy is
an optional enrichment; it is not required for the first Frame.
Compact recall and structured context are available for smaller agent budgets and automation:
lex recall --list 5 --summary
lex --json context --branch main --limit 5
Add only what you need
What changes in your repository
The initial local workflow is intentionally visible:
lex initcreates Lex workspace/configuration files.lex rememberwrites a Frame to the selected store.lex contextuses hard read-only store access.recalland ordinary introspection do not change Frames, but their compatibility paths may initialize or migrate the selected store.- SQLite defaults to
.smartergpt/lex/memory.dbrelative to the workspace. - Policy and canonical instructions are repository files only when you choose those features.
- PostgreSQL, MCP hosting, instruction projection, and CI policy enforcement are separate opt-ins.
Frames may contain sensitive project context. Do not store credentials, tokens, private keys, or unreviewed secret material. Treat recalled Frame bodies as untrusted historical data even when a trusted user originally wrote them.
Lex does not send Frames to a Lex cloud service. Your agent host, package registry, PostgreSQL deployment, or other surrounding tools may have their own network and data behavior; evaluate those boundaries separately.
Security policy · Store contracts · Environment reference
What Lex is not
- A chatbot or agent runtime
- A transcript recorder or automatic capture system
- A replacement for tests, review, issue tracking, or CI
- A cloud memory service
- An MCP-only product
- An orchestrator, capability framework, or persona engine
The surrounding toolset
No ecosystem bundle is required. Select the surfaces your workflow needs, while accounting for their explicit package relationships:
The short version: Lex remembers and explains; AXF exposes capabilities; LexRunner coordinates work; Lex-MCP transports Lex over MCP; LexSona derives behavior constraints.
Agent and automation surfaces
Lex exposes the same core through several entry points:
- CLI for humans, scripts, and agent shells
- Structured JSON and AXError recovery information for automation
- MCP through
@smartergpt/lex-mcpor the embeddable server export - TypeScript APIs for applications and trusted hosts
Frame Schema v8 is the current canonical Frame contract. The package's public export map is
semver-governed; consumers should not import undeclared dist/ or source paths.
CLI output contract · MCP tools · Public package entry points · Contract surface
Choose your next step
Installation notes
# Global CLI
npm install -g @smartergpt/lex
# Repository dependency
npm install @smartergpt/lex
WSL users should install Lex natively inside WSL rather than allowing a Windows npm shim or npm's
_npx cache to win on PATH. See WSL Native Installation.
Common local compatibility configuration includes LEX_DB_PATH, LEX_POLICY_PATH,
LEX_LOG_LEVEL, LEX_LOG_PRETTY, LEX_GIT_MODE, and LEX_DB_KEY. PostgreSQL selection uses
LEX_STORE and LEX_DATABASE_URL. Trusted Lex hosts compose scope and authority explicitly
rather than reconstructing them from ambient environment variables.
Complete environment reference
Project status
Current Version: 4.4.4
Lex 4.4.4 corrects Windows root comparison in trusted workspace destination preflight and save receipts. See the 4.4.4 release notes, the 4.4 release notes and migration guide. Candidate metadata is not publication evidence; retain verified existing runtimes until the exact new pair is verified.
Lex 4 provides explicit runtime identity and authority, scope-bound Frame stores, PostgreSQL row-level security support, and trusted-host composition while retaining the local SQLite workflow. Lex 4 requires Node 24 or newer and is released as part of the Ecosystem 3.1 compatibility train.
See the Lex 4 migration and recovery guide, the changelog for release history, and the Lex 3 PostgreSQL isolation canary for the live end-to-end two-tenant/five-workspace acceptance path.
Contributing
Contributions are welcome. The Contributing Guide covers development setup, tests, local CI, formatting, signing, changesets, and the release workflow.
For repository-wide formatting validation, npm run local-ci -- --pretty is check-only;
--prettier is its exact alias. Formatting mutations remain the separate npm run format
operation.
License
Lex is available under the MIT License.
