memex

Persistent memory for AI coding agents. Your agent remembers what it learned across sessions.

English | 中文 | 日本語 | 한국어 | Español

English

Every time your AI agent finishes a task, it saves insights as atomic knowledge cards with [[bidirectional links]]. Next session, it recalls relevant cards before starting work — building on what it already knows instead of starting from scratch.

No vector database, no embeddings — just markdown files your agent (and you) can read.

Supported platforms

All platforms share the same ~/.memex/cards/ directory. A card written in Claude Code is instantly available in Cursor, Codex, or any other client.

Prerequisites

• VS Code / Copilot: No prerequisites — the extension bundles everything
• Claude Code: No prerequisites — the plugin handles everything
• Pi: Requires Node.js 18+ and npm install -g @touchskyer/memex
• All other platforms (Cursor, Codex, Windsurf, etc.): Requires Node.js 18+

Install

Step 1: Add memex to your editor

Note: If you use Claude Code inside VS Code, follow the Claude Code row — not "VS Code / Copilot". The VS Code extension serves GitHub Copilot only; Claude Code has its own plugin system.

That's it — no extra setup needed. The MCP tool descriptions tell your agent when to recall and retro.

Upgrade

Cross-platform sharing

All clients read and write the same ~/.memex/cards/ directory. Sync across devices with git:

Prerequisite: Auto-create requires GitHub CLI (gh auth login). Or pass your own git remote URL to skip this, including GitLab and self-hosted GitLab remotes.

memex sync --init                # auto-creates private memex-cards repo on GitHub
memex sync --init <repo-url>     # or specify your own repo URL (no gh/glab CLI needed)
memex sync on                    # enable auto-sync after every write
memex sync                       # manual sync
memex sync off                   # disable auto-sync

For GitLab, create an empty private repository first, then pass its SSH or HTTPS remote URL. See the GitLab sync guide for examples.

Browse your memory

memex serve

Opens a visual timeline of all your cards at localhost:3939. Includes a graph view to explore bidirectional links.

If you've set up sync, memex serve opens memra.vercel.app — a web UI with Timeline, Graph view, and Share card. Pass --local to force the local UI instead (useful offline, or when you'd rather not send queries to a third-party web app):

memex serve --local

CLI reference

memex search [query]          # search cards, or list all
memex read <slug>             # read a card
memex write <slug>            # write a card (stdin)
memex links [slug]            # link graph stats
memex archive <slug>          # archive a card
memex serve                   # visual timeline UI
memex sync                    # sync via git
memex mcp                     # start MCP server (stdio)

How it works

Based on Niklas Luhmann's Zettelkasten method — the system behind 70 books from 90,000 handwritten cards:

• Atomic notes — one idea per card
• Own words — forces understanding (the Feynman method)
• Links in context — "this relates to [[X]] because..." not just tags
• Keyword index — curated entry points to the card network

Cards are stored as markdown in ~/.memex/cards/. Open them in Obsidian, edit with vim, grep from terminal. Your memory is never locked in.

Privacy guardrails

Do not put actual secrets, credentials, tokens, or exact secret file contents into memex queries or cards. Use abstract descriptions and redacted examples instead.

Memex rejects high-confidence raw secrets, redacts credentials embedded in URLs before saving, and masks webhook/tokenized URLs in display output. It cannot hide unsafe tool-call arguments that your AI client has already shown in its transcript, so redact before calling tools.

Configuration

Optional settings go in ~/.memex/.memexrc (JSON):

{
  "nestedSlugs": true,
  "searchDirs": ["shared"],
  "experimental": {
    "agenticMemory": true
  }
}

Experimental: Agentic Memory

When experimental.agenticMemory is true, agents gain access to a structured memory skill that guides them through: observe → draft atomic card → enrich metadata → retrieve candidates → decide (create/update/skip) → preview → write → verify.

This produces higher-quality cards with agent-proposed [[wikilinks]] (links are suggested after candidate retrieval and agent review, never added from keyword or embedding similarity alone) and metadata enrichment, compared to the default recall/retro workflow. The feature is default-off and does not change any existing behavior when disabled.

See skills/memex-agentic-memory/SKILL.md for the full skill specification and docs/ARCHITECTURE.md for config details.

中文

AI 编程 agent 的持久记忆系统。让你的 agent 跨会话记住学到的知识。

每次 agent 完成任务后，它会将洞察保存为带有 [[双向链接]] 的原子知识卡片。下次会话时，agent 会先回顾相关卡片再开始工作——基于已有知识继续，而非从零开始。

无需向量数据库，无需 embedding——只是你和 agent 都能读取的 markdown 文件。

支持平台

所有平台共享同一个 ~/.memex/cards/ 目录。在 Claude Code 中写的卡片，在 Cursor、Codex 或其他客户端中即刻可用。

前置要求

• VS Code / Copilot：无需额外安装——扩展内置了所有依赖
• Claude Code：无需额外安装——plugin 自动处理
• Pi：需要 Node.js 18+ 和 npm install -g @touchskyer/memex
• 其他平台（Cursor、Codex、Windsurf 等）：需要 Node.js 18+

安装

第一步：添加 memex 到编辑器

注意： 如果你在 VS Code 里使用 Claude Code，请按照 Claude Code 那一行操作，而非"VS Code / Copilot"。VS Code 扩展仅服务于 GitHub Copilot；Claude Code 有自己的 plugin 系统。

安装完成，无需额外配置。MCP 工具描述会自动告诉 agent 何时 recall 和 retro。

日本語

AIコーディングエージェントのための永続メモリシステム。エージェントがセッションをまたいで学んだことを記憶します。

エージェントがタスクを完了するたびに、[[双方向リンク]]付きのアトミックな知識カードとしてインサイトを保存します。次のセッションでは、作業開始前に関連カードを呼び出し、ゼロからではなく既存の知識の上に構築します。

ベクトルデータベースもembeddingも不要——エージェント（とあなた）が読めるmarkdownファイルだけです。

対応プラットフォーム