ai-memex-cli

# ai-memex-cli

**English** · [简体中文](./README.zh-CN.md)

> **Your AI agents, finally with a memory that compounds.**
>
> AI Memex turns chats, documents, research, and project decisions into a living Markdown knowledge base, maintained by agents and versioned in Git.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/ai-memex-cli.svg)](https://www.npmjs.com/package/ai-memex-cli)

## Why this exists

Most RAG systems rediscover knowledge from scratch on every question — retrieve raw chunks, synthesize, throw it away. **Nothing compounds.** Karpathy's pattern proposes a different shape: the LLM incrementally builds and maintains a structured, interlinked Markdown wiki that sits *between* you and the raw sources. Cross-references are already there. Contradictions have already been flagged. The synthesis already reflects everything you've read.

> **"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."** — Karpathy

This is the oldest idea in information management — Vannevar Bush's 1945 **Memex**. Bush's vision had one gap: *who does the maintenance?* LLMs fill that gap — they don't get bored updating cross-references, and they can touch 15 pages in one pass.

**What ai-memex is:** a Git-backed Markdown knowledge base maintained by your AI agents. The installed `ai-memex` skill decides when to capture, ingest, query, distill, or lint knowledge. The `memex` CLI stays underneath as the mechanical toolbox: fetch sources, search the wiki, validate links/frontmatter, initialize vaults, install agent commands/skills, and parse sessions.

**What it isn't:** a RAG system, an MCP memory server, or a black-box vector store. The CLI makes **zero LLM API calls**. Your local agent (Claude Code, Cursor, Codex, Gemini, …) does the semantic work through the skill. The wiki itself is plain Markdown in a git repo — you can read it, edit it, diff it, blame it.

### Intellectual lineage

This project is explicitly built from [Andrej Karpathy's LLM Wiki idea](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): keep immutable raw sources, have the LLM maintain a structured Markdown wiki, and let knowledge compound through ingest, query, and lint cycles.

ai-memex adds an implementation layer around that pattern:

- an installable `ai-memex` agent skill
- `/memex:*` agent workflows
- a CLI toolbox for fetch/search/lint/status/setup
- multi-agent installation support
- session distillation back into raw material

---

## What `memex` gives you

### Agent-first workflows

Normal use happens inside your agent:

1. **Capture** — `/memex:capture` saves URLs, files, pasted text, or search results into `raw/`.
2. **Ingest** — `/memex:ingest` has the agent compile raw material into durable entity / concept / source / summary pages.
3. **Query** — `/memex:query` answers from your existing wiki with citations instead of re-deriving from scratch.
4. **Distill** — `/memex:distill` turns useful debugging, planning, or research conversations into raw session material.
5. **Lint** — `/memex:lint` runs a two-layer health check (mechanical CLI pass + agent-driven semantic pass) and lets the agent apply safe fixes without flattening contradictions.
6. **Status** — `/memex:status` shows the current vault state and likely next step.

The CLI commands still exist, but they are the toolbox the skill calls when useful:

- `memex fetch`: deterministic web/source capture
- `memex search`: local wiki search
- `memex lint` / `memex link-check`: mechanical health checks
- `memex init` / `memex onboard` / `memex install-hooks`: setup and installation
- `memex distill`: mechanical session discovery/parsing
- `memex status`: vault overview

### Advanced / experimental (not in Karpathy's original)

These layer on top of the core pipeline and are **off by default**. Useful, but opinionated — treat them as experiments and start small.

- **`memex watch --daemon --heal`** — long-lived background loop that runs `ingest → lint → ingest` until the wiki reaches zero issues. Convenient, but it burns agent tokens autonomously; try `memex watch --once` in the foreground first and only daemonize once you trust the loop on your vault.
- **`memex context install`** — writes a marker-delimited "vault digest" block into your project's `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/memex.mdc` so every new agent session opens with the wiki location and a scene summary already in context. This is agent-memory territory rather than Karpathy's pattern; before installing, decide whether it overlaps usefully with Cursor skills / CLAUDE.md you already maintain by hand.
- **Cross-agent prompt layer** — eight agents covered via prompt templates rather than MCP. Works well on Claude Code / Codex / OpenCode; coverage quality varies by agent.

### How it compares to alternatives

| Feature | ai-memex-cli | atomicmemory/llm-wiki-compiler | ussumant/llm-wiki-

... (truncated)