🧠 Memex

Persistent memory layer for AI coding agents.
Claude Code · GitHub Copilot · Cursor · GSD · any CLI tool — no API key required.

Why Memex?

AI coding agents start every session with amnesia. You re-explain the stack, re-justify architecture decisions, re-describe the bug that took three hours last Tuesday.

Memex gives your agents a long-term memory — a structured, queryable store of decisions, context, errors, and progress that persists across sessions and is injected into agent configs automatically.

Quick Start

npx memex-cc           # interactive setup wizard
npm install -g memex-cc  # or install globally

The setup wizard will:

1. Detect your project type (Node/Python/Go/Rust/Ruby)
2. Let you choose which agents to configure (Claude, Copilot, Cursor, etc.)
3. Install git hooks for auto-memory on every commit
4. Save your first memory from README/package.json automatically
5. Show which AI model was detected for smart features

Core Commands

# Save memories
memex remember "We chose PostgreSQL for JSONB support" --type dec --tags db,postgres
memex remember "Stack: Next.js 14 + Postgres + Prisma + Tailwind" --type ctx --tags stack
memex remember "JWT auth — stateless, scales horizontally" --type dec --tags auth

# Retrieve memories
memex recall "database decision"
memex recall "auth approach" --smart        # AI-reranked with explanations

# Inject into agent configs
memex inject --agent claude     # → CLAUDE.md
memex inject --agent copilot    # → .github/copilot-instructions.md
memex inject --agent cursor     # → .cursorrules
memex inject --agent all        # → all detected agents

# Health and maintenance
memex health                    # grade A–F: coverage, freshness, noise
memex status                    # memory dashboard
memex compress                  # merge, prune, summarize, rebuild caches

# Backup and share
memex export                    # → memex-export-<date>.json
memex import backup.json        # merge from bundle (--overwrite / --dry-run)

# Version tracking
memex forget a3f9b2c1           # archive a block
memex history a3f9b2c1          # show version chain

# AI models
memex models                    # show all available models, ranked
memex model-health              # test the best available model

Memory Types

| Type | Label | Description | TTL | |------|-------|-------------|-----| | dec | Decision | Architecture & tech choices | ∞ | | ctx | Context | Stack, goals, constraints | ∞ | | err | Error | Bugs & fixes learned | 180 days | | prog | Progress | Current phase, next steps | 60 days | | usr | User | Preferences, expertise | ∞ | | ref | Reference | Docs, links, APIs | 90 days | | sum | Summary | Auto-compressed session logs | ∞ |

Decisions and context live forever. Ephemeral progress naturally ages out.

AI Models — No API Key Required

Memex auto-detects the best available model. If you have any of these installed, Memex uses them without a separate API key:

| CLI Tool | Provider | How it works | |----------|----------|--------------| | claude (Claude Code) | claude-cli | Uses your existing Claude Code login | | gh (GitHub CLI + Copilot) | gh-copilot | Calls GitHub Models API via gh auth token | | gemini (Google Gemini CLI) | gemini-cli | Uses your existing Gemini CLI auth |

For direct API access, set any of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, MOONSHOT_API_KEY, DEEPSEEK_API_KEY, MISTRAL_API_KEY, or start a local ollama instance.

memex models        # shows ranked list of all detected + available models

The model is auto-selected by quality tier (Tier 1 = best, Tier 4 = fast/local). Override with MEMEX_MODEL=gpt-4o.

Smart Recall

memex recall "auth bug last week" --smart

The --smart flag fetches 3× more candidates via keyword search, then uses the best available AI model to:

• Re-rank results by true semantic relevance to your query
• Show a one-sentence explanation for each result

1. 🏛 [DEC] a3f9b2c1  v1 · 2026-01-10 · 3 days ago
   tags: auth, jwt
   JWT for authentication chosen for stateless scaling
   🤖 AI [95/100]: Directly answers the query — decision about auth architecture

2. 🐛 [ERR] b5f22e9d  v1 · 2026-01-12 · today
   tags: auth, session
   Fixed null session crash in login middleware
   🤖 AI [72/100]: Related auth bug, different from queried topic

Memory Health

memex health

Grades your memory store A–F across 5 dimensions:

🧠 Memex Memory Health Report
────────────────────────────────────────────────────
  Overall grade: B  (82/100)

  Coverage       ████████████████░░░░   80%
  Freshness      ██████████████████░░   90%
  Noise-free     ████████████░░░░░░░░   60%
  Balance        ████████████████████  100%
  Confidence     ██████████████████░░   90%

  Type breakdown:
    ● dec    3 blocks
    ● ctx    2 blocks
    ● err    1 block
    ○ prog   0 blocks
    ○ usr    0 blocks
    ○ ref    0 blocks

  Suggestions:
  → 4 expired + 2 superseded blocks — run `memex compress` to clean up

Export / Import

Share memories between projects, or back them up:

memex export                      # → memex-export-2026-01-15.json
memex export backup.json          # custom filename
memex export --stdout | gzip > backup.json.gz   # pipe-friendly

memex import backup.json           # merge (skip existing by default)
memex import backup.json --overwrite  # replace existing blocks
memex import backup.json --dry-run    # preview what would change

Bundles are self-contained JSON — all block files + index + metadata. No external dependencies.

How Retrieval Works

Hybrid scoring engine — not just keyword search:

score = BM25(0.35) + TF-IDF cosine(0.25) + recency(0.20) + type-weight(0.12) + priority(0.08)
      × confidence-multiplier

• BM25 — lexical precision (Elasticsearch-style)
• TF-IDF cosine — semantic overlap between query and memory body
• Recency decay — recent memories score higher
• Type weights — dec > ctx > err > sum > prog > usr > ref
• Confidence — high=1.0, medium=0.9, low=0.75 multiplies the final score

Use --smart for AI reranking on top of this.

Memory Block Format

Blocks are plain Markdown files in .memex/<type>/<id>.mem.md:

╔MEM╗
id:         a3f9b2c1
type:       dec
proj:       my-app
ts:         2025-01-15T10:30:00Z
version:    v1
tags:       auth,jwt
confidence: high
priority:   2
summary:    JWT chosen for stateless horizontal scaling
╟BODY╢

auth→JWT
reason: stateless-scaling
tradeoff: no-server-side-revocation|mitigation:short-lived-tokens+refresh-rotation

╚/MEM╝

Human-readable, diffable, git-trackable. No database required.

Agent Integration

Claude Code

memex inject --agent claude   # → CLAUDE.md / .claude/CLAUDE.md

Or use the slash command inside Claude Code:

/memex:load-context   ← run at session start
/memex:save-context   ← run at session end
/memex:recall <query>
/memex:remember <body>

GitHub Copilot CLI

memex inject --agent copilot  # → .github/copilot-instructions.md

Cursor

memex inject --agent cursor   # → .cursorrules / .cursor/rules/memex.mdc

All agents at once

memex inject --agent all
memex inject --eject          # remove Memex sections from all agent configs

Auto-Memory (Zero Effort)

Once installed, Memex fires automatically:

Git hook (post-commit):

# Runs after every git commit — extracts memories from your changes
memex auto-extract --from-git

Shell hook (precmd):

# Fires after: npm install, pip install, terraform apply, etc.

Watch mode (background daemon):

memex watch --daemon

Compression

memex compress           # merge, prune, summarize, rebuild caches
memex compress --dry-run # preview
memex compress --no-summarize

• Deduplicate — remove identical/near-identical blocks
• Merge — consolidate similar blocks (cosine > 0.80)
• Prune — archive expired blocks
• Summarize — collapse old prog sessions into a sum block (uses AI if available)
• Rebuild — regenerate BM25 and TF-IDF indexes

Conflict Detection

Saving a dec block checks for contradictions with existing decisions:

⚠ Potential conflict with mem:a3f9b2c1 (similarity: 0.87)
  Body: "auth→JWT|reason:stateless-scaling"
  Use --force to save anyway.

Project Structure

memex/
├── bin/
│   ├── memex.cjs        — CLI entry point (`memex` command)
│   └── install.js       — Setup wizard (`npx memex-cc`)
├── cli/                 — Command handlers
│   ├── remember.cjs
│   ├── recall.cjs       — supports --smart AI reranking
│   ├── inject.cjs
│   ├── compress.cjs
│   ├── forget.cjs
│   ├── history.cjs
│   ├── status.cjs
│   ├── health.cjs       — A–F memory quality grade
│   ├── export.cjs       — portable JSON bundle
│   └── import.cjs       — merge from bundle
├── core/
│   ├── index.cjs        — Public API (require('memex-cc'))
│   ├── models/
│   │   ├── selector.cjs — 40+ model registry, tier ranking, auto-detect
│   │   └── client.cjs   — universal AI client (API + CLI-native)
│   ├── retrieval/       — BM25, TF-IDF, query expansion, intent
│   ├── ranking/         — Scorer, decay, type weights
│   ├── storage/         — Block I/O, index, paths
│   └── compression/     — Dedup, merger, conflicts, summarizer, lifecycle
├── agents/              — Agent adapters (Claude, Copilot, Cursor)
└── tests/
    └── run.cjs          — 92-test suite (no external deps)

Workflow Integration

Add to your session routine:

1. Start session  → /memex:load-context   (agent gets full project context)
2. Do your work
3. End session    → /memex:save-context   (saves what was learned today)

Your agent will never ask you to re-explain decisions it already knows.

Programmatic API

const { recall, remember, writeBlock, createBlock } = require('memex-cc');

// Search memories
const blocks = recall('authentication decisions', '/path/to/project');

// Create and save a block
const block = createBlock({
  type: 'dec',
  proj: 'my-app',
  body: 'Using Redis for session cache — low-latency reads',
  tags: ['redis', 'cache'],
  confidence: 'high',
});
writeBlock(block, memexDir);

// Universal AI call (uses best available model)
const { call } = require('memex-cc/models');
const summary = await call('Summarize this memory: ' + block.body);

License

MIT

Persistent memory layer for AI coding agents.
Claude Code · GitHub Copilot · Cursor · GSD · any CLI tool.

Why Memex?

AI coding agents start every session with amnesia. You re-explain the stack, re-justify the architecture decisions, re-describe the bug that took three hours last Tuesday.

Memex gives your agents a long-term memory — a structured, queryable store of decisions, context, errors, and progress that persists across sessions and gets injected into agent configs automatically.

Quick Start

npx memex-cc           # initialize .memex in your project
npm install -g memex-cc  # or install globally

# Save memories
memex remember "We chose PostgreSQL over MySQL because of JSONB support" --type dec --tags db,postgres
memex remember "Stack: Next.js 14 + Postgres + Prisma + Tailwind" --type ctx --tags stack
memex remember "JWT auth—stateless, scales horizontally" --type dec --tags auth

# Retrieve memories
memex recall "database decision"
memex recall "authentication approach" --type dec

# Inject into your agent config
memex inject --agent claude     # → CLAUDE.md
memex inject --agent copilot    # → .github/copilot-instructions.md
memex inject --agent cursor     # → .cursorrules
memex inject --agent all        # → all detected agents

# Maintain memory health
memex compress                  # merge, prune, summarize, rebuild caches
memex status                    # see what's stored

# Other
memex forget a3f9b2c1           # archive a block by id
memex history a3f9b2c1          # show version chain

Memory Types

| Type | Label | Description | TTL | |------|-------|-------------|-----| | dec | Decision | Architecture & tech choices | ∞ | | ctx | Context | Stack, goals, constraints | ∞ | | err | Error | Bugs & fixes learned | 180 days | | prog | Progress | Current phase, next steps | 60 days | | usr | User | Preferences, expertise | ∞ | | ref | Reference | Docs, links, APIs | 90 days | | sum | Summary | Auto-compressed session logs | ∞ |

Decisions and context live forever. Ephemeral progress naturally ages out.

How Retrieval Works

Memex uses a hybrid scoring engine — not just keyword search:

score = BM25(0.35) + TF-IDF cosine(0.25) + recency(0.20) + type-weight(0.12) + priority(0.08)
      × confidence-multiplier

• BM25 — lexical precision (Elasticsearch-style)
• TF-IDF cosine — semantic overlap between query and memory body
• Recency decay — recent memories score higher
• Type weights — dec > ctx > err > sum > prog > usr > ref
• Confidence — high=1.0, medium=0.9, low=0.75 multiplies the final score

Results are ranked, not just filtered.

Memory Block Format

Blocks are plain Markdown files in .memex/<type>/<id>.mem.md:

╔MEM╗
id:         a3f9b2c1
type:       dec
proj:       my-app
ts:         2025-01-15T10:30:00Z
version:    v1
tags:       auth,jwt
confidence: high
priority:   2
summary:    JWT chosen for stateless horizontal scaling
╟BODY╢

auth→JWT
reason: stateless-scaling
tradeoff: no-server-side-revocation|mitigation:short-lived-tokens+refresh-rotation

╚/MEM╝

Human-readable and diffable. No database required.

Agent Integration

Claude Code

memex inject --agent claude

Writes a <!-- memex:start --> ... <!-- memex:end --> block into CLAUDE.md (or .claude/CLAUDE.md). Re-running updates the section in place.

GitHub Copilot

memex inject --agent copilot

Injects into .github/copilot-instructions.md.

Cursor

memex inject --agent cursor

Injects into .cursorrules or .cursor/rules/memex.mdc.

Remove injection

memex inject --eject

Strips the Memex section from all detected agent configs.

Compression

Over time, memories accumulate noise. Run memex compress to:

• Deduplicate — remove identical or near-identical blocks
• Merge — consolidate similar blocks (TF-IDF cosine > 0.80)
• Prune — archive expired blocks
• Summarize — collapse old prog sessions into a sum block
• Rebuild caches — regenerate BM25 and TF-IDF indexes

memex compress           # full compression
memex compress --dry-run # preview changes without writing
memex compress --no-summarize  # skip session summarization

Conflict Detection

When you save a dec (decision) block, Memex checks for contradictions with existing decisions in the same project. If you store "Using PostgreSQL" and later try to store "Using MongoDB", you'll get a warning:

⚠ Potential conflict with mem:a3f9b2c1 (similarity: 0.87)
  Body: "auth→JWT|reason:stateless-scaling"
  Use --force to save anyway.

Versioning

Blocks support version chains:

version:     v2
prev:        a3f9b2c1

memex history <id> walks the chain:

$ memex history b4e12f8a
v2  b4e12f8a  2025-02-01  "auth→JWT+refresh-rotation"  (current)
v1  a3f9b2c1  2025-01-15  "auth→JWT"                   (archived)

Programmatic API

const { recall, remember, writeBlock, createBlock } = require('memex-cc');

// Search memories
const blocks = recall('authentication decisions', '/path/to/project');

// Create and save a block
const block = createBlock({
  type: 'dec',
  proj: 'my-app',
  body: 'Using Redis for session cache — low-latency reads',
  tags: ['redis', 'cache'],
  confidence: 'high',
});
writeBlock(block, memexDir);

Project Structure

memex/
├── bin/
│   ├── memex.cjs        — CLI entry point (`memex` command)
│   └── install.js       — Setup wizard (`npx memex-cc`)
├── cli/                 — Command handlers
│   ├── remember.cjs
│   ├── recall.cjs
│   ├── inject.cjs
│   ├── compress.cjs
│   ├── forget.cjs
│   ├── history.cjs
│   └── status.cjs
├── core/
│   ├── index.cjs        — Public API (require('memex-cc'))
│   ├── retrieval/       — BM25, TF-IDF, query expansion, intent
│   ├── ranking/         — Scorer, decay, type weights
│   ├── storage/         — Block I/O, index, paths
│   └── compression/     — Dedup, merger, conflicts, summarizer, lifecycle
├── agents/              — Agent adapters (Claude, Copilot, Cursor)
└── tests/
    └── run.cjs          — 64-test suite (no external deps)

Workflow Integration

Add to your session routine:

# Start of session
memex recall "$(git log --oneline -3)"  # recall recent context
memex inject --agent all                 # refresh agent configs

# During session (key decisions)
memex remember "Chose Zod over Yup — better TS inference" --type dec --tags validation

# End of session
memex remember "Completed auth module, next: user profile API" --type prog
memex compress                           # merge & summarize

Requirements

• Node.js 18+
• No API keys required — all processing is local

License

MIT