Memex

Memex

The memory layer for AI coding tools. Works with Claude, Cursor, Copilot, Ollama, Gemini — any agent, paid or free.

---

Every AI coding session starts with the same problem: the agent has no idea who you are, what you're building, or what you decided last week. You re-explain the stack. You paste context. You re-discover the same gotchas. Every. Single. Time.

Memex fixes this. It gives every AI agent — Claude, Cursor, Copilot, a local Ollama model, anything — persistent memory of your project. One session builds on the last. Decisions are remembered. Mistakes aren't repeated. Context follows the project, not the agent.

    Day 1                              Day 2
      │                                  │
  memex start claude               memex resume claude
      │                                  │
  "Build me a checkout flow"        "Continue from where we left off"
      │                                  │
  Claude works...                   Claude: "Yesterday we finished the
      │                              cart logic. Still need to wire up
  You close the terminal            Stripe webhooks. Want me to start?"
      │                                  │
  [Memex saves everything]          Back in flow in 10 seconds.

Switch tools mid-project without losing context. Start a feature in Claude CLI, continue it in Cursor, pick it up tomorrow with a free Ollama model. The memory lives in your project — not in any one tool.

---

Install

npm install -g @patravishek/memex

Memex uses a small AI call at the end of each session to compress the transcript into structured memory. You can use any of these — paid or free:

| Provider | How to set up | Cost | |---|---|---| | Ollama (local) | ollama pull llama3.1 then export OLLAMA_BASE_URL=http://localhost:11434 | Free, offline | | Groq | console.groq.com → free API key → export GROQ_API_KEY=... | Free tier | | Google Gemini | aistudio.google.com → free API key → export GEMINI_API_KEY=... | Free tier | | Anthropic | export ANTHROPIC_API_KEY=sk-ant-... | Paid | | OpenAI | export OPENAI_API_KEY=sk-... | Paid | | LiteLLM proxy | export LITELLM_API_KEY=... LITELLM_BASE_URL=... | Your pricing |

Add your chosen key to ~/.zshrc (or ~/.bashrc):

# Example — pick whichever provider you're using (see Configuration below)

# Free: Groq
export LITELLM_BASE_URL=https://api.groq.com/openai/v1
export LITELLM_API_KEY=gsk_...
export LITELLM_MODEL=groq/llama-3.1-8b-instant

# OR: Anthropic (paid)
export ANTHROPIC_API_KEY=sk-ant-...

Then reload your shell:

source ~/.zshrc

That's the entire setup. See [Configuration](#configuration) below for all supported providers including free options.

---

The two commands you need

memex start claude      # Day 1 — or any time you start fresh on a project
memex resume claude     # Every session after — Claude picks up where it left off

That's it. Everything else is automatic.

Using Cursor, Copilot, or another IDE agent instead of the CLI? Initialize without launching any agent:

memex init              # creates .memex/memex.db and sets up the project
memex setup-mcp         # connects Cursor Agent / Copilot via MCP

---

What it actually feels like

Day 1 — Starting a new project:

cd ~/my-project
memex start claude

You work with Claude for a couple of hours. Build some features, make decisions, hit a few problems. When you're done, close the terminal — any way you like (Ctrl+C, close the window, just kill it). Memex detects all of these and saves everything before the process fully exits.

Day 2 — Coming back:

cd ~/my-project
memex resume claude

Claude responds:

Continuing from our last session — we were building the checkout flow.

Here's what I have in memory:
• Project: my-app (Next.js + Stripe + PostgreSQL)
• Last session: Finished cart persistence, fixed guest cart bug
• Still pending: Wire up Stripe webhooks, add payment failure handling
• Watch out: Stripe webhook events can arrive out of order under load

What would you like to work on?

Claude is your personal engineering assistant — it remembers your project, your decisions, your mistakes, and exactly where you left off.

---

How it works

memex start claude
      ↓
Session recorded locally (.memex/sessions/)
      ↓
You exit → AI compresses transcript → .memex/memex.db
      ↓
memex resume claude
      ↓
Claude gets a short context hint + MCP tools connected
      ↓
Claude calls get_context(), get_gotchas()... on demand
      ↓
No wasted tokens. No performance warnings. Just context.

Memory is project-scoped — each project has its own independent database at .memex/memex.db. Nothing is shared between projects unless you choose to.

---

Install

Prerequisites

• macOS
• Node.js 18+
• An API key from Anthropic, OpenAI, or a LiteLLM enterprise proxy
• Claude CLI — install here

Via npm / pnpm / yarn

# npm
npm install -g @patravishek/memex

# pnpm
pnpm add -g @patravishek/memex

# yarn
yarn global add @patravishek/memex

Available on npm at @patravishek/memex.

From source

git clone https://github.com/patravishek/memex.git
cd memex
npm install && npm run build && npm link

---

Configuration

Memex reads everything from your shell environment — no config file required.

Free: Ollama (local, offline, no account needed)

Run any open-source model locally. No API key, no usage limits, works offline.

# Install Ollama from https://ollama.com, then:
ollama pull llama3.1        # or mistral, codellama, deepseek-coder, etc.

export OLLAMA_BASE_URL=http://localhost:11434
export LITELLM_MODEL=ollama/llama3.1

Works on Apple Silicon Macs without a GPU. Recommended model: llama3.1 or deepseek-coder-v2.

Free: Groq (fast, free API tier)

Groq offers a generous free tier with very fast inference on Llama and Mixtral.

export LITELLM_BASE_URL=https://api.groq.com/openai/v1
export LITELLM_API_KEY=gsk_...          # from console.groq.com
export LITELLM_MODEL=groq/llama-3.1-8b-instant

Free: Google Gemini (free API tier)

Google AI Studio offers free access to Gemini 1.5 Flash.

export LITELLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta
export LITELLM_API_KEY=AIza...          # from aistudio.google.com
export LITELLM_MODEL=gemini/gemini-1.5-flash

Paid: Anthropic

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_MODEL=claude-3-haiku-20240307   # optional, haiku is cheapest

Paid: OpenAI

export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o-mini   # optional

Enterprise: LiteLLM proxy

Route through your corporate proxy for centralised key management. Session data never leaves your network.

export LITELLM_API_KEY=your_litellm_key
export LITELLM_BASE_URL=https://litellm.your-company.com
export LITELLM_MODEL=claude-3-haiku
export LITELLM_TEAM_ID=your_team_id   # optional

Provider auto-detection

Memex picks the provider automatically based on what's set:

1. LiteLLM / Ollama / Groq / Gemini — if LITELLM_API_KEY + LITELLM_BASE_URL are both set
2. Anthropic — if ANTHROPIC_API_KEY is set
3. OpenAI — if OPENAI_API_KEY is set

---

All commands

memex init

Initialize Memex for a project without launching any agent. Creates .memex/memex.db and sets up .gitignore. Use this when working with IDE-based agents like Cursor or Copilot that don't need the CLI session wrapper.

cd ~/my-project
memex init

After running, open the Memex sidebar in VS Code / Cursor — or run memex setup-mcp to connect your IDE agent via MCP.

---

memex start [command]

Start a tracked session on a project for the first time.

memex start claude
memex start aider
memex start claude --project /path/to/project

On first run, Memex automatically adds .memex/ and .mcp.json to the project's .gitignore so session data is never accidentally committed.

When you exit — whether by typing exit, pressing Ctrl+C, or closing the terminal window — you'll see:

✔ Memory updated — focus: Implementing the checkout flow
  Pending tasks: 3, gotchas: 1, conversation turns saved: 24

If the process is killed before compression finishes (e.g., the window is force-closed), Memex writes a recovery marker automatically. The next memex resume picks it up:

  Recovering interrupted session from last run...
✔ Memory updated — focus: Implementing the checkout flow

Nothing is lost.

---

memex resume [command]

Resume with full context restored. Claude connects to Memex memory tools automatically on startup.

memex resume claude

Claude gets a brief summary of where things stand, then queries memory on demand — no 35k char dump, no performance warnings.

v0.4 options:

# Focus memory on a specific area — sorts gotchas, tasks, decisions by relevance
memex resume claude --focus "stripe webhooks"

# Control how much context is injected (1=one-liner, 2=key facts, 3=full)
memex resume claude --no-mcp --tier 2

# Hard cap on context size (~1 token = 4 chars)
memex resume claude --no-mcp --max-tokens 1000

# Combine: focus + budget
memex resume claude --no-mcp --focus "auth bug" --max-tokens 800

# Fall back to full context dump (no MCP)
memex resume claude --no-mcp

The --focus topic is saved to memory automatically — future resumes pick it up without you retyping it.

---

memex focus [topic]

View or set the current focus topic for this project.

# Set a new focus (saved to memory, used on next resume automatically)
memex focus "stripe payment integration"

# List current focus and full history
memex focus --list

# Clear focus entirely
memex focus --clear

  memex — focus history

  Current: stripe payment integration

  Past topics (most recent first):
    1. checkout redirect bug
    2. auth refactor
    3. onboarding UX

Focus history keeps the last 10 topics. The AI also updates currentFocus naturally during end-of-session compression as work shifts — so history builds up even without explicitly running memex focus.

---

memex status

See what Memex currently knows about your project.

memex status

  memex — project memory

  Project: my-app
  What this project does:
  E-commerce platform with Next.js and Stripe

  Tech stack: Next.js, TypeScript, Prisma, PostgreSQL
  Current focus: Implementing the checkout flow

  Pending tasks:
    - Wire up Stripe webhooks
    - Add payment failure handling

  Gotchas:
    - Stripe webhook events can arrive out of order under load

  Sessions recorded: 4
  Database: /my-app/.memex/memex.db

---

memex history

List past sessions with dates, durations, and one-line summaries.

memex history
memex history -n 50

  #12  Feb 18, 2026  [claude]  42m
       Finished cart persistence, fixed guest cart bug on page refresh.

  #11  Feb 17, 2026  [claude]  1h 5m
       Set up Stripe webhook handler and wrote integration tests.

---

memex show

View the full transcript and summary of any past session.

memex show 12

---

memex search

Full-text search across all past session summaries.

memex search "stripe webhook"
memex search "authentication bug"

---

memex setup-mcp

Make Memex memory tools permanently available in Claude without using memex resume.

# For this project only (commit to share with teammates)
memex setup-mcp

# For every Claude session on your machine
memex setup-mcp --global

After this, just run claude normally and say "resume from where we left off" — Claude will find the memory automatically.

---

memex compress

Manually re-run compression on the latest session. Useful if you want to force a re-summarize.

memex compress

In most cases you don't need this — if a session was interrupted (e.g., terminal force-closed), Memex automatically recovers it on the next memex resume.

---

memex prune [days]

Delete session records older than N days (default: 30).

memex prune        # removes sessions older than 30 days
memex prune 7      # removes sessions older than 7 days

---

memex forget

Clear all memory for the current project.

memex forget                  # clear everything
memex forget --keep-sessions  # clear memory fields, keep session history

---

MCP tools (available inside Claude sessions)

When Claude connects via MCP, it can call these tools on demand:

| Tool | What it does | |---|---| | get_context() | Project summary, stack, current focus. Accepts optional focus (relevance sort) and tier (1/2/3 verbosity) | | get_tasks() | Pending tasks | | get_decisions() | Key architectural decisions with reasons | | get_gotchas() | Pitfalls to avoid | | get_important_files() | Files worth knowing about | | get_recent_conversation() | Last N turns from previous session | | search_sessions("query") | Search past session history | | get_session(id) | Full detail of a specific session | | save_observation(type, content) | Save a note, task, decision, or gotcha mid-session |

save_observation is particularly useful — Claude can save important discoveries immediately without waiting for end-of-session compression.

Claude can also request a relevance-sorted view mid-session:

get_context(focus="payment flow", tier=2)

---

Privacy — `` tag

Wrap any text in a session with … and Memex will strip it from the transcript before it's sent to the AI for compression. The raw session log is unaffected (local only), but the compressed memory will never contain that content.

Useful for passwords accidentally typed, personal context, internal URLs, or anything you don't want stored permanently:

  Staging DB password: s3cr3t-temp

The AI sees [content excluded by ] in its place.

---

Project structure

.memex/
├── memex.db          # SQLite database — memory + full session history
└── sessions/
    ├── *.jsonl       # Structured session logs
    └── *-raw.txt     # Raw terminal recordings

.memex/ and .mcp.json are automatically added to the project's .gitignore on the first memex start or memex resume. Nothing needs to be done manually.

If .memex/ was already committed to a repo before upgrading to v0.4, run once:

git rm -r --cached .memex/
git commit -m "chore: stop tracking .memex directory"

---

Works with any agent

Memory lives in .memex/memex.db — a local SQLite file that every agent reads from and writes to via MCP. Switch tools mid-project without losing a single byte of context.

CLI agents (session recording + auto-compression):

| Agent | Command | |---|---| | Claude CLI | memex start claude | | Aider | memex start aider | | Shell-GPT | memex start sgpt | | Any CLI agent | memex start your-agent |

IDE agents (MCP tools available on demand):

| Agent | How | Status | |---|---|---| | Cursor Agent | Auto-configured via .cursor/mcp.json — install the VS Code extension or run memex setup-mcp | ✅ Verified | | OpenAI Codex | Auto-configured via .vscode/mcp.json — run memex setup-mcp | ✅ Verified | | GitHub Copilot | Auto-configured via .vscode/mcp.json — same extension | ✅ Verified | | Any MCP client | Run memex serve --project /path/to/project | ✅ Works |

Starter prompt for IDE agents:

When you open an IDE agent on a project, paste this once to restore

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: patravishek
• Source: patravishek/memex
• License: MIT

Install and usage instructions live in the source repository linked above.