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.

What is in this repo

• src/ — Intellex CLI, Claude integration, mem0 bridge, 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
• Claude integration in src/lib/agent-claude.ts
• mem0 backend wrapper in src/lib/memory-mem0.ts
• Python mem0 bridge in src/bridges/mem0_bridge.py
• Backfill pipeline in src/lib/backfill.ts

Requirements

• Bun
• Python 3
• mem0ai installed for Python
• an OpenAI-compatible API key for mem0 fact extraction

Install 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 mem0

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

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

The package name intellex is available on npm.

Install globally:

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

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 is required for the mem0 bridge
• mem0ai must be installed for memory-backed commands
• run Intellex from the workspace root where you want .intellex/ to live

Claude hooks

Intellex can install Claude Code hooks for:

• SessionStart: prime + small background backfill + briefing
• UserPromptSubmit: semantic search for prompt context

Use the setup command to install hooks.

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

Backfill depends on Claude session logs existing for the current workspace under ~/.claude/projects/<encoded-workspace-path>. If no project directory exists yet, ix backfill will correctly report that there is no projects directory for the workspace.

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.

Verification status

Verified during migration:

• bun test passes in the Intellex source tree
• npm package name intellex is available
• npm pack succeeds
• 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 the automation repo 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

Still required before publish:

• final README polish if we want to tighten wording further
• npm login on this machine (npm whoami currently requires auth)
• actual npm publish