Intellex

Intellex is a local-first memory tool for coding agents. It focuses on the part agent memory systems often miss: not just storing useful information, but surfacing it at the right workflow boundary so it can still change behavior.

How it works

Intellex wires memory into agent workflow boundaries:

• Claude hooks retain both SessionStart (prime + recent backfill) and UserPromptSubmit (semantic recall).
• Codex/Pi prompt-time recall searches memory before planning, without adding lifecycle hooks.
• Pluggable memory backends support embedded mem0 or an existing agentmemory REST server.
• Manual backfill cleans supported agent transcripts and stores durable lessons.
• Benchmark mode tests pre-plan and pre-execute recall directly on chronological coding tasks.

What is in this repo

• src/ — Intellex CLI, Claude/Codex/Pi integrations, mem0 and agentmemory backends, backfill pipeline
• bench/ — benchmark harness for testing memory policies on SWE-bench CL
• tests/ — Bun tests for the CLI/tooling

Core implementation pieces:

• Bun CLI in src/cli.ts
• Agent integrations in src/lib/agent-claude.ts, agent-codex.ts, and agent-pi.ts
• Memory backends in src/lib/memory-mem0.ts and src/lib/memory-agentmemory.ts
• Python mem0 bridge in src/bridges/mem0_bridge.py
• Backfill pipeline in src/lib/backfill.ts

Requirements

• Bun
• One memory backend:
  • mem0: Python 3, mem0ai, and an OpenAI-compatible API key
  • agentmemory: a reachable agentmemory REST server (defaults to http://localhost:3111)

For mem0, install the Python dependency:

pip3 install mem0ai

Local development setup

From the repo root:

bun install
bun run src/cli.ts init
bun run src/cli.ts setup <claude|codex|pi> <mem0|agentmemory>

If you are running Intellex inside another repo as a submodule or from source, run the CLI from that workspace root so .intellex/ is created in the right project.

If you are using the mem0 backend, set .intellex/.env with your own provider details, for example:

LLM_API_KEY=your-api-key
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=

Notes:

• LLM_BASE_URL is optional and can point to any OpenAI-compatible endpoint
• embeddings stay local via fastembed
• no default public repo config should assume a specific private router or API key

For agentmemory, Intellex uses its REST API. The default URL is http://localhost:3111; override it per workspace in .intellex/.env:

AGENTMEMORY_URL=http://localhost:3111
# Optional when the server has AGENTMEMORY_SECRET configured:
AGENTMEMORY_SECRET=
# Optional explicit scope; otherwise Intellex uses the workspace basename:
AGENTMEMORY_PROJECT_NAME=

Configure an agent and the backend together:

ix setup claude agentmemory
# or
ix setup codex agentmemory

Common commands

bun run src/cli.ts status --json
bun run src/cli.ts memory
bun run src/cli.ts search "query"
bun run src/cli.ts store "important fact"
bun run src/cli.ts backfill --latest 1 --dry-run
bun test

Install from npm

Intellex is now published on npm.

Install globally:

npm install -g intellex
intellex --help
ix --help

Yes — the ix alias works after install. The package publishes both CLI names:

• intellex
• ix

Or use it without a global install:

npx intellex --help
npx ix --help

Important runtime notes:

• the package is currently Bun-first internally, so Bun must be available on the machine
• Python 3 and mem0ai are required only for the embedded mem0 backend
• the agentmemory backend requires a reachable agentmemory server
• run Intellex from the workspace root where you want .intellex/ to live

Agent integrations

Choose one project-local integration:

• ix setup claude: installs Claude Code SessionStart (prime + small background backfill) and UserPromptSubmit (semantic recall) hooks in .claude/settings.local.json.
• ix setup codex: installs only a Codex UserPromptSubmit semantic-recall command hook in .codex/hooks.json.
• ix setup pi: installs only a Pi before_agent_start semantic-recall extension in .pi/extensions/intellex-memory.ts.

Codex and Pi do not receive session-start, stop, automatic backfill, or subagent lifecycle hooks. Their transcript ingestion is manual through ix backfill. Setup is idempotent and removal preserves unrelated project hooks/extensions. Use ix setup <agent> --check or --remove to inspect or remove an integration.

Codex and Pi project-local integrations are only configured after setup; the host must trust the project before loading .codex/hooks.json or .pi/extensions/. Intellex does not modify or infer host trust configuration, so setup/check report configured; requires host project trust rather than claiming the integration is operational.

agentmemory backend

ix setup agentmemory selects an existing agentmemory server as Intellex's memory backend. Intellex stores backfilled sessions through POST /agentmemory/remember, recalls prompt context through project-filtered POST /agentmemory/search, verifies matched memories or sessions through the REST API, and lists memories through GET /agentmemory/memories. Exact project checks prevent memories from another workspace—or legacy unscoped records—from entering prompt context.

The agentmemory backend integration is for Claude Code and Codex: their existing Intellex prompt hooks recall from agentmemory whenever backend: agentmemory is selected. No Pi adapter or hook changes are included. Pi recall is already working through its existing before_agent_start extension, which delegates to the backend-neutral ix hook pi → Memory.search() path.

Removing the agentmemory backend clears only the local Intellex selection. It never deletes server-side agentmemory data.

Concurrency note

Embedded local Qdrant does not safely support concurrent access from multiple bridge processes. Intellex serializes mem0 bridge access with a local file lock in .intellex/mem0/.bridge.lock to avoid overlapping search/list/add calls in normal local usage.

If higher-throughput concurrent access becomes a product requirement, prefer moving to a Qdrant server instead of embedded local mode.

Backfill note

ix backfill manually reads the configured agent's session logs for the current workspace: Claude under ~/.claude/projects/<encoded-workspace-path>, Codex under date-partitioned ~/.codex/sessions/, and Pi under ~/.pi/agent/sessions/. If no matching sessions exist, it reports that directly. Claude may also launch a small recent backfill from its retained SessionStart hook; Codex and Pi never install automatic backfill hooks.

Benchmark harness

The benchmark harness now lives in bench/.

It compares:

• none — no memory
• faiss — passive retrieval over prior reflections
• intellex — workflow-triggered memory injection plus transcript backfill

See bench/README.md for details.

License

MIT. See LICENSE.

Verification status

Verified during migration:

• bun test passes in the Intellex source tree
• npm package name intellex is available
• npm pack succeeds with a CLI-focused tarball that excludes benchmark data and source tests
• clean tarball install works in a fresh temp directory
• npx intellex --help, npx ix --help, npx intellex init, and npx intellex status --json work from that clean install
• real-workspace verification from a separate workspace root succeeded for ix setup mem0, ix memory, ix search, and ix backfill --latest 1
• stale mem0 bridge lock recovery was implemented, tested, and verified in a real workspace
• the public repo snapshot excludes local state and build artifacts

Publish status:

• npm package published: intellex
• global install path verified
• intellex and ix entrypoints both verified after install