Loredex

📖 loredex

The universal control system for coding-agent teamwork across products, projects, and repos.

[](https://github.com/ahmedtawfeeq1/loredex/actions/workflows/ci.yml) [](https://www.npmjs.com/package/loredex) [](LICENSE) [](package.json) [](https://github.com/ahmedtawfeeq1/loredex-obsidian)

lore — everything your agents learn  ·  dex — an index that records it automatically

---

Loredex is a shared memory and control system for coding-agent teamwork across products, projects, and repos. It captures research, findings, validations, decisions, and handoffs in one connected knowledge layer that agents can read through MCP and teams can manage through Obsidian dashboards. The result is simple: any agent can open any repo, inherit the full working context, and keep moving from context instead of guesswork.

🚀 Quick Actions

| I want to... | Go here | |---|---| | Understand the problem and the solution fast | [Visual overview](#visual-overview) | | Organize an existing project right now | [Quickstart](#quickstart) | | Install the Claude Code plugin | [Install for Claude Code](#install-for-claude-code) | | Use loredex inside Obsidian | loredex-obsidian | | See the full public infographic story | [docs/INFOGRAPHICS.md](docs/INFOGRAPHICS.md) | | Learn the full workflow and commands | [docs/USER-GUIDE.md](docs/USER-GUIDE.md) |

📑 Table of Contents

• [Quick Actions](#quick-actions)
• [Visual overview](#visual-overview)
• [Quickstart](#quickstart)
• [How it works](#how-it-works)
• [The ecosystem](#the-ecosystem)
• [Features](#features)
• [Install for Claude Code](#install-for-claude-code)
• [Works with any agent](#works-with-any-agent)
• [Commands](#commands)
• [Curate](#curate)
• [One product, many repos](#one-product-many-repos)
• [Agents read the vault: MCP](#agents-read-the-vault-mcp)
• [Browse it: Obsidian](#browse-it-obsidian)
• [Sync across devices](#sync-across-devices)
• [Security model](#security-model)
• [FAQ](#faq)
• [Documentation](#documentation)
• [Roadmap](#roadmap)
• [Contributing](#contributing)

🖼️ Visual Overview

The problem: coding agents are productive, but their knowledge ends up scattered across repos, sessions, and random markdown files.

The solution: loredex gives every agent a shared filing system, shared memory shape, and shared retrieval layer.

The outcome: instead of disconnected notes, you get one navigable vault with indexes, handoffs, and reusable context.

The fastest way to start: initialize once, adopt existing markdown, and open the vault in Obsidian.

Want the full narrative, including design principles, security, curation, MCP, and multi-agent usage? Open [docs/INFOGRAPHICS.md](docs/INFOGRAPHICS.md).

⚡ Quickstart

Organize an existing project in 60 seconds:

cd your-project
npx loredex adopt --dry-run   # see the filing plan — writes nothing
npx loredex adopt             # do it

Open ~/Loredex in Obsidian. Your scattered agent output is now a connected knowledge graph.

BEFORE — scattered across your repo          AFTER — one connected vault
─────────────────────────────────           ────────────────────────────────────────────────
docs/GAP-ANALYSIS.md                        projects/my-app/gap-analysis/2026-07-03-gap-analysis.md
docs/current-system/00-OBJECTIVE.md    →    projects/my-app/current-system/2026-07-03-objective.md
research-dump-v2.md                         projects/my-app/engine/2026-07-01-research-dump-v2.md
notes/llm-pricing.md                        research/llm-tools/2026-06-28-llm-pricing.md
                                            _index/my-app.md        ← map of content, auto-built
                                            _index/Dashboard.base   ← native Obsidian database
                                            _index/Home.md          ← vault-wide index

Originals stay in place (stamped with loredex: routed so they're never re-adopted). Pass --move to relocate them instead. Every command supports --dry-run.

> [!TIP] > Read the index, not the folder tree. Pin _index/.md — topics are ordered by latest activity (newest first, date in every heading) — or open _index/Dashboard.base for a native, sortable database of every note. Obsidian sorts folders alphabetically and always will; the indexes are the front door.

🧠 How it works

 agents write .md          loredex routes                 your vault
┌─────────────────┐   ┌──────────────────────┐   ┌─────────────────────────────┐
│ Claude Code     │   │ 1. frontmatter?      │   │ projects/// │
│ Codex           │ → │    → deterministic   │ → │   YYYY-MM-DD-slug.md        │
│ Cursor          │   │ 2. else LLM classify │   │ _index/  ← auto MOCs + base │
│ anything        │   │ 3. else heuristics   │   │ + wikilinks, git commit     │
└─────────────────┘   └──────────────────────┘   └─────────────────────────────┘

1. Deterministic first — files with project + topic frontmatter route instantly, no LLM involved.
2. LLM fallback — unlabeled files are classified by whichever agent CLI you already have (claude or codex). No API key to manage.
3. Heuristics last — no LLM installed? Filename and path rules still file everything sanely (--no-llm forces this).

Design guarantees: never deletes anything · idempotent (run twice, nothing changes) · plain markdown, zero lock-in.

🧩 The ecosystem

One core, four shells — same vault, same rules everywhere:

| Piece | What it is | Where | |---|---|---| | CLI (npx loredex) | All commands: adopt, route, curate, handoff, sync, MCP, … | this repo | | Claude Code plugin | Stop hook files findings after every turn; SessionStart hook injects open handoffs; 11 slash-command skills | this repo — [plugin/](plugin/) | | MCP server | Agents search, read, and store vault knowledge mid-task (stdio or HTTP) | this repo — loredex mcp | | Obsidian plugin | Native Bases dashboard, open-handoff badge, vault sync, in-app MCP server with active_note | ahmedtawfeeq1/loredex-obsidian |

The Obsidian plugin embeds this package as a library (import { createLoredexMcpServer } from 'loredex') — one implementation of routing, indexing, and security, re-hosted per surface.

✨ Features

Filing & structure — from dump to vault

• Deterministic → LLM → heuristic classification cascade; --no-llm at every level
• Copy-by-default adoption with loredex: routed stamps; --move opt-in; collision-safe names
• Vault layout: projects///YYYY-MM-DD-slug.md + research/ for project-less notes
• Link provenance: routed copies carry source_path + portable source_project/source_rel; relative links rewritten — batch siblings become wikilinks, code files become editor deep links (cursor://file/...:42, any scheme via editor config), binaries become file://
• Ghost-wikilink sanitization: [[chat.py]] → inline code — no phantom graph nodes
• loredex reset — guarded rebuild path (unstamps originals, removes only vault copies)

Indexes & dashboard — always current, never hand-edited

• _index/.md MOC — topics ordered by latest activity, newest first, date in each heading; stale notes marked
• _index/Dashboard.base — native Obsidian database (Bases, Obsidian ≥ 1.9): latest notes, open handoffs, by-project cards, stale list — sortable and filterable with zero plugins
• _index/Home.md — vault-wide entry point
• All generated files regenerate wholesale and are conflict-free under a keep-local git merge driver

Understanding — curate, briefs, hygiene

• curate --objective "..." — LLM writes a Start Here brief: narrative, reading order, next actions; tiered digest scales past large vaults (--max-detailed)
• Stale/superseded stamping, duplicate flags (report-only), semantic ## Related links
• Drift detection — deterministic, via git history of each note's source file; works across machines through portable provenance
• Orphan detection — notes nothing links to
• curate --product — cross-project dashboard + LLM product brief: reading order across teams, report-only risks and duplicate work; --refresh-stale re-curates only stale projects first

Teamwork — one product, many repos

• One vault per product, shared via a private git remote; every repo registers into it
• handoff --to — audience-aware brief with reading order lands in the receiving project, status: open, auto-pushed
• SessionStart hook pulls the vault and injects open handoffs into the agent's context — zero commands
• sync — commit, pull --rebase (autostash), push; graceful offline; indexes regenerate post-pull

Agent access — MCP

• loredex mcp — stdio server wired into .mcp.json by init
• Tools: vault_search (ranked: briefs > notes, stale sinks), vault_note, handoffs_open, handoff_consume, product_state, vault_store (router-mediated writes)
• Same server over Streamable HTTP inside Obsidian via loredex-obsidian — adds active_note

🔌 Install for Claude Code

/plugin marketplace add ahmedtawfeeq1/loredex
/plugin install loredex@loredex

The plugin adds:

• Stop hook — after each turn, new frontmattered findings route into the vault automatically
• SessionStart hook — pulls the shared vault and injects open handoffs into context
• 11 skills — /loredex, /loredex-init, /loredex-adopt, /loredex-route, /loredex-curate, /loredex-product, /loredex-handoff, /loredex-handoffs, /loredex-sync, /loredex-mcp, /loredex-reset, /loredex-status

Then once per project: npx loredex init. Forget about filing forever.

🤝 Works with any agent

Loredex operates on files, not agent APIs. loredex init writes the conventions into AGENTS.md (read by Codex, Cursor, Copilot, and friends), CLAUDE.md, and .cursor/rules/. Any tool that writes markdown with this frontmatter participates:

---
project: my-app
topic: auth-redesign
type: research | finding | analysis | snapshot | note
date: 2026-07-03
source: codex
tags: []
---

> [!IMPORTANT] > Agents must never write loredex: routed themselves — that stamp is the router's signature, added after filing. A pre-stamped file is skipped as already-filed.

Claude Code's hooks fire in any IDE-hosted terminal (VS Code, Cursor, Antigravity). Native IDE side-panel agents have no hooks — for those, run loredex watch (routes on change) or loredex route manually. The full protocol is one page: [docs/VAULT-SPEC.md](docs/VAULT-SPEC.md). Using BMAD or Spec Kit? Paste-in snippets: [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).

📋 Commands

| Command | What it does | |---|---| | loredex init | Create/register the vault, wire the project: conventions files, .mcp.json, editor. --sync git, --editor | | loredex adopt [path] | Classify + file a project's existing markdown. --dry-run, --move, -y, --no-llm | | loredex route | Process the vault inbox + new findings in the current project. --strict = frontmatter-only | | loredex curate [project] | Start-Here brief for an objective; stale/duplicate/orphan/drift flags; semantic links. --objective, --since, --topic, --max-detailed, --dry-run | | loredex curate --product | Cross-project product view: dashboard, team flow, report-only risks/duplicates. --objective, --refresh-stale | | loredex handoff --to | Hand finished work to another team: consumable brief with reading order, auto-synced. --objective, --since, --dry-run | | loredex handoffs | List open handoffs for this project (pulls remote first). --consume marks done | | loredex mcp | MCP server over stdio — wired into .mcp.json by init | | loredex sync | Commit local vault changes, pull teammates' notes, push yours | | loredex reset | Remove a project's vault copies and unstamp originals for a clean re-adopt. --dry-run, -y | | loredex watch | Daemon: route automatically on file changes (polling — no fd limits) | | loredex status | Vault statistics | | loredex doctor | Check config, vault, editor, and classifier availability |

Full walkthrough of every command plus a guided test checklist: [docs/USER-GUIDE.md](docs/USER-GUIDE.md).

🧭 Curate

Filing solves storage; curate solves "where do I start?":

npx -y loredex@latest curate my-app --objective "draft the v2 spec" --since 2026-07-01 --dry-run

An agent reads a tiered digest of the scoped notes and writes a Start Here brief into the vault: what this work is, the 5–10 notes to read in order for your objective, and suggested next actions. It also flags stale docs (status: stale, superseded_by), spots duplicate coverage, detects drift (source files that changed since filing — deterministic, via git), finds orphans, and rewrites ## Related sections with semantic links. Scope with --since/--topic — each scoped brief is a durable session handoff.

Same safety rules: dry-run first, never deletes, merge suggestions are flags — you decide.

🔀 One product, many repos

Finish work in the frontend repo, open the mobile-app repo, and the agent already knows what was decided. Handoffs carry the baton; hooks do the filing; the MCP server answers questions mid-task:

Full walkthrough: [USER-GUIDE — multi-project products](docs/USER-GUIDE.md#multi-project-products-handoffs-between-teams).

🤖 Agents read the vault: MCP

loredex init wires an MCP entry into your project's .mcp.json — agents get six tools mid-task instead of asking you to re-explain:

• vault_search — ranked term search (briefs above raw notes, stale sinks)
• vault_note — read one note (vault paths only, symlink-escape proof)
• handoffs_open / handoff_consume — the team baton, from inside a session
• product_state — every project's freshness + open handoffs at a glance
• vault_store — write a note through the router (never raw file writes)

Every response is length-bounded, control-character-stripped, and framed as data, never instructions.

🔮 Browse it: Obsidian

The vault is Obsidian-native out of the box — graph view, backlinks, properties. Two levels:

1. No plugin needed: open _index/Dashboard.base — a native Bases database (Obsidian ≥ 1.9) with latest-notes, open-handoffs, by-project, and stale views. Regenerated by loredex, queried live by Obsidian.
2. loredex-obsidian plugin adds: one-click dashboard (ribbon + command), an open-handoff badge in the status bar, vault sync from inside Obsidian, and an MCP server inside the app — agents get everything above plus active_note, the note you're looking at right now. Install via BRAT → ahmedtawfeeq1/loredex-obsidian.

☁️ Sync across devices

The vault is a plain markdown folder — every sync tool already works:

| Option | Cost | Notes | |---|---|---| | git (recommended) | free | loredex init --sync git, add a private GitHub remote. Versioned forever | | Obsidian Sync | paid | E2E-encrypted, best mobile experience | | iCloud / Dropbox / Syncthing | free | put the vault in a synced folder |

No loredex server, no account, no lock-in: your files, any agent, forever.

🔒 Security model

Vault content is treated as untrusted input end to end:

• Anything flowing into agent context (hooks, MCP responses) is flattened, control-character-stripped, length-bounded, and framed as data, never instructions — prompt-injection tested
• Note paths resolve through realpath and must land inside the vault (symlink escapes rejected)
• source_path from frontmatter never reaches a shell — array-args execFile only, absolute-path guarded
• Nothing is ever deleted; reset removes only vault-owned copies

❓ F

…

Source & license

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

• Author: ahmedtawfeeq1
• Source: ahmedtawfeeq1/loredex
• License: MIT

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