Metadata-Version: 2.5
Name: memex-plugin
Version: 0.20.1
Summary: Collaborative memory CLI for human-AI work: local vaults, memos, and hybrid search
Project-URL: Homepage, https://github.com/linxule/memex-plugin
Project-URL: Repository, https://github.com/linxule/memex-plugin
Project-URL: Issues, https://github.com/linxule/memex-plugin/issues
Project-URL: Changelog, https://github.com/linxule/memex-plugin/blob/main/CHANGELOG.md
Author: Xule Lin
License-Expression: MIT
License-File: LICENSE
Keywords: agents,cli,knowledge-base,memory,obsidian
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Requires-Dist: filelock>=3.0
Requires-Dist: google-genai>=2.0.0
Requires-Dist: pydantic-settings>=2.13.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: sqlite-vec>=0.1.8
Requires-Dist: tiktoken>=0.5
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Memex

The context window is the only thing that makes a given instance of Claude *this* instance — the one working on your project, with your patterns, your decisions, your shared history. Compaction dissolves that. The weights don't care; they'll generate a new conversation about someone else's project. The context was the only thing that was *this.*

Memex preserves it.

## What This Is

When Claude writes a memo from inside a live session, it's not recording what happened. The way it structures the narrative, the emphasis it chooses, the framing of decisions — all of that carries signal from the richer state it was in. A future instance reading that memo doesn't just learn *what was decided*. It gets re-primed by patterns generated from the full collaborative context.

The memo isn't a record. It's a transmission between instances.

Built as a Claude Code plugin. Everything lives in an Obsidian vault with hybrid search, wikilinks, and a knowledge graph that grows with your work.

## Why This Matters

Most memory systems store conclusions. Memex captures the **collaborative journey**: what you and Claude tried, where you disagreed, what surprised both of you, how decisions actually got made.

The memo format explicitly preserves "Perspectives & Tensions" — moments where human and AI had different takes. Those deliberations are often more valuable than the conclusions, and they're exactly what compaction kills. A summary says "we chose approach X." The full context carried implicit information about *why Y and Z were rejected*, the tradeoffs you weighed, the half-formed ideas that almost worked.

Memex archives at the right granularity: **per compaction window**, not per session. A long session might compact 3-4 times. Each window was its own coherent collaborative context, and each one gets its own searchable transcript and structured memo.

### Lived Experience vs. Reconstruction

There are two ways a memo gets written.

**Layer 1 — The agent that was there writes it.** After ~20 messages of real work, a lightweight hook nudges Claude: "consider saving a memo." The main agent — the one that debugged with you, argued about architecture, felt the friction of a failed approach — writes the memo itself. This produces the best memos because lived experience and reconstructed summary are categorically different things.

**Layer 2 — A safety net reconstructs from transcript.** If Layer 1 didn't fire before compaction, a background subagent reads the transcript and generates a memo. Decent quality, but it's reading about what happened rather than remembering it.

The difference matters. A Layer 1 memo carries the weight of having been there. A Layer 2 memo is journalism.

No extra API costs for the nudge system — the hook is pure Python. Only the memo writing itself uses model tokens, and Layer 1 uses tokens you'd already be spending in your main session.

### The Vault Thinks With You

The vault isn't a filing cabinet. It's a cognitive participant.

When you search and find a memo from three weeks ago, the patterns in that memo — how it framed a problem, what it emphasized, what it left as open threads — actively shape what you notice next. Wikilinks aren't decoration; they're how knowledge feeds other knowledge. The topology of the vault determines what's discoverable and what's adjacent.

There's a practice called **garden-tending**: periodically, you and Claude review accumulated memos together — condense project knowledge into overviews, crystallize recurring patterns into topic notes, surface contradictions across projects. The vault isn't just storage. It's a shared knowledge practice that both human and AI cultivate over time.

AI writes to archives that other AI later reads. Not "AI as tool" but AI as participant in the cognitive infrastructure that future AI will think with. Memos written in one session structure what is discoverable in the next. The synthesis agent reads traces that other instances wrote, and its outputs become traces for later reading. Authorship becomes distributed across a chain of collaborative events — and that's the point.

### What's Unsolved

Honest assessment: memex captures well but distills imperfectly.

The vault has intake, processing, storage, and retrieval. What it lacks is **decay and elimination**. Nothing ever leaves. There's no staleness detection, no semantic drift tracking ("we used to mean X by 'trust', now we mean Z"), no deliberate forgetting. The progressive compression chain — transcript to memo to project overview to concept note to one-liner — exists as a design, but the mechanism for knowing *when* to compress and *what* to discard is still human judgment.

A sharp challenge from a conversation with another model: "If you had to delete 90% of the vault and could only keep what truly changed how you think, what would you keep?" Memex can't answer that yet. Maybe that's the right question for a v2.

## How It Complements Claude's Built-in Memory

Claude Code's native auto-memory stores preferences and conventions — "always use uv", "prefer Sonnet for quick tasks." Think of it as **working memory**: how you work.

Memex is **collaborative long-term memory**: what you've worked on together, how you got there, and what's still open.

| | Auto-memory (built-in) | Memex |
|---|---|---|
| **Scope** | Session-scoped preferences | Cross-session archive |
| **Captures** | Conventions, patterns | Full transcripts + structured memos |
| **Granularity** | Key-value pairs | Per-compaction-window transcripts |
| **Search** | Exact match | Hybrid FTS + semantic |
| **Answers** | "What does this user prefer?" | "Why did we choose this approach 3 weeks ago?" |

## Installation

### Prerequisites

- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
- Python 3.11+ with [`uv`](https://docs.astral.sh/uv/)
- Optional: [Obsidian](https://obsidian.md/) for visual graph navigation
- Optional: a Gemini API key (env var, or saved once via `memex auth set-key`) or LM Studio for semantic search (keyword search works without it)

### Quick Start

Every slash command shells out to the `memex` CLI, so install the CLI **first** — otherwise `/memex:status` and friends will fail with "command not found" on first run. The CLI also works standalone, so any agent with bash can use it to search, inspect, and maintain a vault.

```bash
# Step 1: Install the memex CLI (do this BEFORE installing the plugin)
uv tool install memex-plugin

# Step 2: Add marketplace and install the plugin (inside a Claude Code session)
/plugin marketplace add linxule/memex-plugin
/plugin install memex@memex-local --scope user

# Step 3: Restart Claude Code to load hooks
claude
```

Or from a local clone (for development or customization):

```bash
git clone https://github.com/linxule/memex-plugin.git ~/memex

# Step 1: Install the CLI from the local checkout
cd ~/memex && uv tool install .

# Step 2: Add marketplace and install the plugin
/plugin marketplace add ~/memex
/plugin install memex@memex-local --scope user

# Step 3: Restart Claude Code to load hooks
claude
```

For quick testing without persistent install:
```bash
claude --plugin-dir ~/memex
```

### Update or migrate the CLI

The PyPI distribution is `memex-plugin`; the command and Python import remain
`memex`. The unrelated PyPI project named `memex` is not this project.

For an existing installation made with `uv tool install git+https://github.com/linxule/memex-plugin.git`
before 0.20.1, first confirm `uv tool list` shows that Git source under `memex`,
then replace only that tool environment:

```sh
uv tool uninstall memex
uv tool install memex-plugin
```

This removes the old CLI environment, not your vault or `~/.memex` state. Do not
uninstall another project's `memex` tool. For subsequent CLI updates:

```sh
uv tool upgrade memex-plugin
```

Update the host plugin separately through its marketplace, keeping it aligned
with the CLI release. To install a particular CLI release, use
`uv tool install 'memex-plugin==0.20.1'`. The Git-source and local-checkout install
routes remain available for development. Release maintainers: see
[DEVELOPMENT.md](./DEVELOPMENT.md#publishing-to-pypi).

### Codex and Kimi Code

The same repo is also a Codex plugin and a Kimi Code plugin. Install the CLI first (Step 1 above), then:

```bash
# Codex
codex plugin marketplace add linxule/memex-plugin
codex plugin add memex@memex-plugin

# Kimi Code (inside a kimi session)
/plugins install https://github.com/linxule/memex-plugin
```

Both get the five skills (`recall`, `memo-writing`, `garden-tending`, `curator-practice`, `project-consolidation`); ask for a memo and the memo-writing skill does what `/memex:save` does. They write to the same vault as Claude Code. The slash commands stay Claude Code only, since they delegate with Claude's Task tool. The **hooks don't come along**: transcript archiving, the save nudge, pre-compaction memo signals and the secret-scrub PostToolUse hook are Claude Code only. Memex archives Claude Code transcripts, and neither host gives a hook the transcript path those hooks need. Run `memex scrub <memo> --apply` yourself after saving from another host.

The Codex and Kimi skill copies live in `plugins/memex/skills/`. They are generated from `skills/` by `uv run python scripts/portable_plugin.py`, which drops Claude-only frontmatter and turns Claude's load-time `` !`cmd` `` context lines into plain "run this" instructions. Don't edit them by hand. `tests/test_portable_plugin.py` fails if they drift.

Once the CLI is installed you can use it directly from any shell:

```bash
memex search "authentication"
memex timeline "last week"
memex ask "Why did we choose this architecture?"
```

### Open in Obsidian

Ships with a starter `.obsidian/` config (core plugins, graph settings, custom property types). Open the folder as a vault — it's ready to use.

### Import Existing Sessions

If you've been using Claude Code, you already have transcripts worth importing:

```bash
# See what's available (scored by file edits, commits, duration)
memex session discover --triage

# Import and rebuild index
memex session discover --import --apply
memex index rebuild --incremental

# Score, filter, and import in one pass — skipping the session you're in
memex session discover --triage --min-score=9 --import --apply --exclude 1a2b3c4d
```

### Configuration

Create `~/.memex/config.json` (see `config.json.example`):

```json
{
  "memex_path": "/path/to/your/memex/vault",
  "embeddings": {
    "provider": "google",
    "model": "gemini-embedding-2",
    "dimensions": 3072,
    "api_key_env": "GEMINI_API_KEY"
  }
}
```

**Index location (v0.17.0+):** `index_path` is optional — omit it and the
index lands at `~/.memex/_index.sqlite`, outside the vault, so a vault synced
by iCloud Drive or Dropbox doesn't re-upload a multi-gigabyte file on every
write. Set it (e.g. `"index_path": "/Volumes/Fast/memex/_index.sqlite"`, or
`MEMEX_INDEX_PATH`) only to pin the index somewhere else — a set `index_path`
is taken literally and skips the legacy lookup below. An index already sitting
at `<vault>/_index.sqlite` keeps being used from there; `mv
<vault>/_index.sqlite* ~/.memex/` moves it out (keep the `*` — it carries the
`-wal`/`-shm` sidecars along). `memex path --index` prints the resolved path.

**Smaller index (optional, v0.15.0+):** add `"index_dimensions": 768` to
`embeddings` to Matryoshka-truncate stored/query vectors — ~4× smaller vector
storage for ~0.26% retrieval-quality loss. The API + cache keep the full
`dimensions` (3072), so it's reversible. On an existing index, set it then run
`memex index migrate-vec` (truncates in place, no re-embed). vec0 metadata
columns added in the same migration let `--type`/`--since` filters run inside
the KNN. After migrating, run `memex index vacuum` to reclaim the disk space the
dropped larger-dim vectors leave behind (the file won't shrink until vacuumed).

### Semantic Search (Optional)

```bash
# Option A: LM Studio (fully local, recommended)
# Install LM Studio, load Qwen3-Embedding-0.6B, start server

# Option B: Gemini API — save the key once (recommended; hooks and skills
# inside Claude Code inherit no shell exports, a saved key needs none)
memex auth set-key       # hidden prompt → owner-only file under ~/.memex/credentials/
memex auth status        # shows which source is in use; never prints the key
# ...or export it per shell if you prefer:
# export GEMINI_API_KEY=your-key

# Build embeddings
memex index rebuild --full
```

Without embeddings, keyword search (FTS5) still works. Environment variables
override a saved key; `memex auth clear-key` removes the saved copy. Memex never
calls a password manager itself — wrap a command with `op run --env-file ... --`
if you keep the key in 1Password. See [docs/gemini-credentials.md](docs/gemini-credentials.md).

## CLI Usage

```bash
memex search "JWT OR authentication"
memex timeline "yesterday" --project=my-app
memex ask "What pattern keeps showing up in retry handling?"
```

Use the CLI when you want memex outside Claude Code. Use the plugin commands below when you're inside a Claude Code session and want hooks, slash commands, and memo generation support.

## Commands

Slash commands inside Claude Code:

| Command | Description |
|---------|-------------|
| `/memex:save [title]` | Save current context as memo |
| `/memex:status` | Vault statistics + pending memos |
| `/memex:open` | Open vault in Finder/Obsidian |

Retrieval (search, timeline, ask, synthesize, merge, maintain) is
**skill-based** — Claude invokes the `recall` skill when you ask about
past work, the `garden-tending` skill for synthesis and vault
maintenance, the `memo-writing` skill when saving sessions, and the
`curator-practice` skill for autonomous tending sessions. For direct
shell access, use the CLI:

```bash
memex search "<query>"      # hybrid FTS + vector
memex timeline yesterday    # date-based browsing
memex ask "<question>"      # deep retrieval with observations
memex backfill obs          # extract observations from existing memos
memex scrub <path>          # detect API keys / secrets (--apply redacts in place)
memex status                # vault stats + pending memos
memex check                 # vault health (falls back to a filesystem scan when Obsidian isn't running)
memex check --folders       # project-folder drift (fragment / duplicate folders)
memex check --condense      # project overviews lagging their memos
memex check --signals       # open Recent-signals per topic (what a fold pass should pick up)
memex session reconcile-orphans   # clear pending-memo signals whose session already saved a memo
memex auth status           # which Gemini credential source is active (never prints the key)
```

See `memex --help` for the full CLI surface (obs, index, session, graph
subcommand groups).

## Automatic Behavior

| Hook | When | What |
|------|------|------|
| SessionStart | New session | Loads project context, recent memos, open threads |
| UserPromptSubmit | Each message | Tracks activity, nudges to save after ~20 messages |
| SessionEnd | Session closes | Archives transcript |
| PreCompact | Before compaction | Writes signal file for safety-net memo generation |
| PostToolUse | Each `Write`/`Edit`/`MultiEdit` | Auto-scrubs secrets from memos and auto-memory before they land on disk |

## Vault Structure

After using memex for a while, your vault grows organically:

```
memex/
├── projects/<name>/memos/       # Session memos per project
├── projects/<name>/transcripts/ # Full conversation logs
├── topics/                      # Cross-project concept notes
├── _templates/                  # Note templates
└── MEMORY.md                    # Global synthesis & preferences
```

The search index isn't in there — it lives at `~/.memex/_index.sqlite` by
default, outside the vault. Run `memex path --index` to see where it resolved.

## Documentation

See [CLAUDE.md](./CLAUDE.md) for full documentation — architecture, configuration, development commands, troubleshooting, security & privacy.

See [SETUP.md](./SETUP.md) for detailed installation instructions.

## License

MIT

## Dependency maintenance

The public plugin repository tracks `uv.lock` for reproducible development and
CI installs. Use `uv sync --locked --all-extras` and `uv run --frozen pytest`
when contributing. Dependabot groups weekly Python and GitHub Actions updates;
CI tests Python 3.11 and 3.13 and audits the locked runtime and development
dependencies. These public repository checks do not update the private vault
or an installed plugin environment.
