{"id":46394954,"url":"https://github.com/linxule/memex-plugin","last_synced_at":"2026-06-09T20:00:26.611Z","repository":{"id":341585249,"uuid":"1170707072","full_name":"linxule/memex-plugin","owner":"linxule","description":"Collaborative memory plugin for Claude Code — persistent, searchable, interconnected. Captures the collaborative process as structured memos in an Obsidian vault with hybrid search.","archived":false,"fork":false,"pushed_at":"2026-05-25T14:54:38.000Z","size":580,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T15:33:18.346Z","etag":null,"topics":["ai-memory","claude-code","claude-code-plugin","knowledge-management","memos","obsidian","search","transcripts"],"latest_commit_sha":null,"homepage":"https://github.com/linxule/memex-plugin","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linxule.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-02T12:30:00.000Z","updated_at":"2026-05-25T14:54:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/linxule/memex-plugin","commit_stats":null,"previous_names":["linxule/memex-plugin"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/linxule/memex-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linxule%2Fmemex-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linxule%2Fmemex-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linxule%2Fmemex-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linxule%2Fmemex-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linxule","download_url":"https://codeload.github.com/linxule/memex-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linxule%2Fmemex-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34123172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","claude-code","claude-code-plugin","knowledge-management","memos","obsidian","search","transcripts"],"created_at":"2026-03-05T09:33:33.485Z","updated_at":"2026-06-09T20:00:26.602Z","avatar_url":"https://github.com/linxule.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memex\n\nThe 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.*\n\nMemex preserves it.\n\n## What This Is\n\nWhen 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.\n\nThe memo isn't a record. It's a transmission between instances.\n\nBuilt as a Claude Code plugin. Everything lives in an Obsidian vault with hybrid search, wikilinks, and a knowledge graph that grows with your work.\n\n## Why This Matters\n\nMost 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.\n\nThe memo format explicitly preserves \"Perspectives \u0026 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.\n\nMemex 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.\n\n### Lived Experience vs. Reconstruction\n\nThere are two ways a memo gets written.\n\n**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.\n\n**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.\n\nThe difference matters. A Layer 1 memo carries the weight of having been there. A Layer 2 memo is journalism.\n\nNo 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.\n\n### The Vault Thinks With You\n\nThe vault isn't a filing cabinet. It's a cognitive participant.\n\nWhen 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.\n\nThere'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.\n\nAI 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.\n\n### What's Unsolved\n\nHonest assessment: memex captures well but distills imperfectly.\n\nThe 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.\n\nA 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.\n\n## How It Complements Claude's Built-in Memory\n\nClaude 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.\n\nMemex is **collaborative long-term memory**: what you've worked on together, how you got there, and what's still open.\n\n| | Auto-memory (built-in) | Memex |\n|---|---|---|\n| **Scope** | Session-scoped preferences | Cross-session archive |\n| **Captures** | Conventions, patterns | Full transcripts + structured memos |\n| **Granularity** | Key-value pairs | Per-compaction-window transcripts |\n| **Search** | Exact match | Hybrid FTS + semantic |\n| **Answers** | \"What does this user prefer?\" | \"Why did we choose this approach 3 weeks ago?\" |\n\n## Installation\n\n### Prerequisites\n\n- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)\n- Python 3.11+ with [`uv`](https://docs.astral.sh/uv/)\n- Optional: [Obsidian](https://obsidian.md/) for visual graph navigation\n- Optional: `GEMINI_API_KEY` or LM Studio for semantic search (keyword search works without it)\n\n### Quick Start\n\nEvery 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.\n\n```bash\n# Step 1: Install the memex CLI (do this BEFORE installing the plugin)\nuv tool install git+https://github.com/linxule/memex-plugin.git\n\n# Step 2: Add marketplace and install the plugin (inside a Claude Code session)\n/plugin marketplace add linxule/memex-plugin\n/plugin install memex@memex-plugins --scope user\n\n# Step 3: Restart Claude Code to load hooks\nclaude\n```\n\nOr from a local clone (for development or customization):\n\n```bash\ngit clone https://github.com/linxule/memex-plugin.git ~/memex\n\n# Step 1: Install the CLI from the local checkout\ncd ~/memex \u0026\u0026 uv tool install .\n\n# Step 2: Add marketplace and install the plugin\n/plugin marketplace add ~/memex\n/plugin install memex@memex-plugins --scope user\n\n# Step 3: Restart Claude Code to load hooks\nclaude\n```\n\nFor quick testing without persistent install:\n```bash\nclaude --plugin-dir ~/memex\n```\n\nOnce the CLI is installed you can use it directly from any shell:\n\n```bash\nmemex search \"authentication\"\nmemex timeline \"last week\"\nmemex ask \"Why did we choose this architecture?\"\n```\n\n### Open in Obsidian\n\nShips with a starter `.obsidian/` config (core plugins, graph settings, custom property types). Open the folder as a vault — it's ready to use.\n\n### Import Existing Sessions\n\nIf you've been using Claude Code, you already have transcripts worth importing:\n\n```bash\n# See what's available (scored by file edits, commits, duration)\nmemex session discover --triage\n\n# Import and rebuild index\nmemex session discover --import --apply\nmemex index rebuild --incremental\n```\n\n### Configuration\n\nCreate `~/.memex/config.json` (see `config.json.example`):\n\n```json\n{\n  \"memex_path\": \"/path/to/your/memex/vault\",\n  \"embeddings\": {\n    \"provider\": \"google\",\n    \"model\": \"gemini-embedding-2\",\n    \"dimensions\": 3072,\n    \"api_key_env\": \"GEMINI_API_KEY\"\n  }\n}\n```\n\n### Semantic Search (Optional)\n\n```bash\n# Option A: LM Studio (fully local, recommended)\n# Install LM Studio, load Qwen3-Embedding-0.6B, start server\n\n# Option B: Gemini API\nexport GEMINI_API_KEY=your-key\n\n# Build embeddings\nmemex index rebuild --full\n```\n\nWithout embeddings, keyword search (FTS5) still works.\n\n## CLI Usage\n\n```bash\nmemex search \"JWT OR authentication\"\nmemex timeline \"yesterday\" --project=my-app\nmemex ask \"What pattern keeps showing up in retry handling?\"\n```\n\nUse 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.\n\n## Commands\n\nSlash commands inside Claude Code:\n\n| Command | Description |\n|---------|-------------|\n| `/memex:save [title]` | Save current context as memo |\n| `/memex:status` | Vault statistics + pending memos |\n| `/memex:open` | Open vault in Finder/Obsidian |\n\nRetrieval (search, timeline, ask, synthesize, merge, maintain) is\n**skill-based** — Claude invokes the `recall` skill when you ask about\npast work, the `garden-tending` skill for synthesis and vault\nmaintenance, the `memo-writing` skill when saving sessions, and the\n`curator-practice` skill for autonomous tending sessions. For direct\nshell access, use the CLI:\n\n```bash\nmemex search \"\u003cquery\u003e\"      # hybrid FTS + vector\nmemex timeline yesterday    # date-based browsing\nmemex ask \"\u003cquestion\u003e\"      # deep retrieval with observations\nmemex backfill obs          # extract observations from existing memos\nmemex scrub \u003cpath\u003e          # detect API keys / secrets (--apply redacts in place)\nmemex status                # vault stats + pending memos\nmemex check                 # vault health (falls back to a filesystem scan when Obsidian isn't running)\n```\n\nSee `memex --help` for the full CLI surface (obs, index, session, graph\nsubcommand groups).\n\n## Automatic Behavior\n\n| Hook | When | What |\n|------|------|------|\n| SessionStart | New session | Loads project context, recent memos, open threads |\n| UserPromptSubmit | Each message | Tracks activity, nudges to save after ~20 messages |\n| SessionEnd | Session closes | Archives transcript |\n| PreCompact | Before compaction | Writes signal file for safety-net memo generation |\n| PostToolUse | Each `Write`/`Edit`/`MultiEdit` | Auto-scrubs secrets from memos and auto-memory before they land on disk |\n\n## Vault Structure\n\nAfter using memex for a while, your vault grows organically:\n\n```\nmemex/\n├── projects/\u003cname\u003e/memos/       # Session memos per project\n├── projects/\u003cname\u003e/transcripts/ # Full conversation logs\n├── topics/                      # Cross-project concept notes\n├── _templates/                  # Note templates\n├── _index.sqlite                # Search index (auto-generated)\n└── MEMORY.md                    # Global synthesis \u0026 preferences\n```\n\n## Documentation\n\nSee [CLAUDE.md](./CLAUDE.md) for full documentation — architecture, configuration, development commands, troubleshooting, security \u0026 privacy.\n\nSee [SETUP.md](./SETUP.md) for detailed installation instructions.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinxule%2Fmemex-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinxule%2Fmemex-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinxule%2Fmemex-plugin/lists"}