📖 loredex

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

CI npm license: MIT node ≥ 20 Obsidian plugin Desktop app

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

loredex ecosystem  ·  📖 loredex (CLI + core) (you are here)  ·  🖥️ Desktop app  ·  🔮 Obsidian plugin

loredex — every project's agents write markdown; loredex classifies, files, indexes, and hands it off between projects, 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
Organize an existing project right now Quickstart
Install the Claude Code plugin Install for Claude Code
Use loredex inside Obsidian loredex-obsidian
Install the native desktop app (mac/win/linux) Desktop app · download
See the full public infographic story docs/INFOGRAPHICS.md
Learn the full workflow and commands docs/USER-GUIDE.md

📑 Table of Contents

🖼️ Visual Overview

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

The problem Loredex solves

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

Loredex architecture

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

Before and after comparison

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

Get started flow

Want the full narrative, including design principles, security, curation, MCP, and multi-agent usage? Open 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/<project>.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/<project>/<topic>/ │
│ 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.

🆚 How it compares

"Why not just tell my agent to write frontmatter to a folder and open Obsidian?"

That convention is loredex — the difference is loredex makes it automatic, enforced, and queryable:

  • Automatic, not remembered. The Claude Code Stop hook files every finding when the turn ends. A hand-rolled convention depends on the agent remembering to write to the right place every single time — and agents drift. Miss it once and the note is lost again.
  • Cross-project, not one folder. handoff --to <project> routes an audience-aware brief into another repo's lane, with status and attribution. A folder can't hand work between teams.
  • Agent-readable memory. Agents query the vault mid-task over MCP (vault_search, vault_note, product_state) — the vault is live memory, not a graveyard you scroll.
  • Kept honest. curate writes Start Here briefs, flags stale/superseded notes, detects drift from source files via git, and finds orphans. A folder rots silently.
  • One writer. CLI, hooks, agents, and app all write through the same loredex engine — nobody files "their own way." A convention is enforced by no one.

You keep everything good about the folder (plain markdown, git, zero lock-in — move any file by hand) and lose the part that never actually happens on its own: the filing.

loredex Folder + convention ADR tools (adr-tools / log4brains) Notion / Confluence GitHub wiki obsidian-wiki
Captures agent output automatically ✅ hook per turn ❌ must remember ❌ manual adr new ❌ manual ❌ manual ~ skill-invoked
Agent-native (any CLI, via files) ✅ ~ if you wire it ❌ ❌ (API only) ❌ ✅
Cross-project handoffs ✅ ❌ ❌ ~ pages ❌ ❌
Agents read it back (MCP) ✅ ❌ ❌ ❌ ❌ ~ MCP
Plain markdown, no lock-in ✅ ✅ ✅ ❌ ~ ✅
Team sync (git, built-in) ✅ ~ DIY ~ DIY ✅ hosted ✅ hosted ~
Stale / drift detection ✅ ❌ ❌ ❌ ❌ ~ lint

(~ = partial or needs setup. obsidian-wiki is the closest peer — single-user, ingestion is skill-invoked; loredex's edge is automatic hook capture plus the team/handoff/desktop layer.)

On search: knowledge comes back out mainly through agents querying over MCP — the app and Obsidian search views are secondary, for humans browsing. That search is deterministic term-ranking today (semantic search is on the roadmap); since MCP uses the same engine, that applies to the agent path too.

🧩 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/
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
Desktop app Native mac/win/linux app: handoff board, atlas graph, contract timeline, live sync, in-app MCP ahmedtawfeeq1/loredex-desktop

The Obsidian plugin and desktop app both embed this package as a library (import { createLoredexMcpServer } from 'loredex') — one implementation of routing, indexing, and security, re-hosted per surface. Anything that writes vault markdown is a shared loredex export, so the CLI, agents, plugin, and app can never disagree about what a write means.

✨ Features

  • 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/<project>/<topic>/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 <project> — guarded rebuild path (unstamps originals, removes only vault copies)
  • _index/<project>.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
  • 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
  • One vault per product, shared via a private git remote; every repo registers into it
  • handoff --to <project> — 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
  • 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. Using BMAD or Spec Kit? Paste-in snippets: 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 <scheme>
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 <project> 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 <name> 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 relink Repair vault wikilinks broken by cross-batch routing (bare slug → dated note name). --dry-run
loredex reset <project> 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

Agent-ops dexes — a dex created with loredex init --type agent-ops is an agency operating a fleet of client AI-agent deployments (managers → clients → pipelines/agents → stages) instead of research notes. It adds:

Command What it does
loredex new <kind> Scaffold structure: client <name>, pipeline <client> <name>, agent <client> <name>, stage <client> <pipeline> <name> (--before/--after renumbers)
loredex clients The client roster: list (default), tag / untag / set-tags
loredex workspace <client> Generate a client's agent tooling from workspace.yml (.mcp.json, .claude settings, AGENTS.md) — secrets from env, never committed. --check, --from <client>

The full layout, rules, and file contract are in docs/DEX-SPEC.md; the Loredex Desktop app drives all of this from a UI.

Full walkthrough of every command plus a guided test checklist: 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:

How context flows from one repo's agent to another through the loredex vault

Full walkthrough: USER-GUIDE — multi-project products.

🤖 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.

🖥️ Desktop app

Prefer a purpose-built native app over Obsidian? Loredex Desktop ships for macOS, Windows, and Linux — download an installer from the latest release:

OS File First launch (unsigned)
macOS (Apple Silicon, 14+) Loredex-<version>-arm64.dmg xattr -cr /Applications/Loredex.app then codesign --force --deep --sign - /Applications/Loredex.app
Windows (10/11, x64) Loredex.Setup.<version>.exe SmartScreen → More info → Run anyway
Linux (x64) .AppImage (any distro) or .deb (Debian/Ubuntu) chmod +x *.AppImage and run

It embeds the same loredex package the CLI and agents use — one engine, in-process — and adds a handoff inbox/outbox board (accept / decline / snooze / consume, replies, threads), a zoomable Atlas graph, an API-contract change timeline, live team sync against your git remote, and an in-app MCP server agents auto-discover. On an agent-ops dex it also becomes a fleet control room — a Clients view, per-client onboarding, an embedded terminal, and client-scoped AI chat panels. No Obsidian, no plugins, no account.

Why the app over Obsidian? Obsidian is a great markdown editor/browser; the desktop app is built to operate the loredex workflow — running handoffs with attributed transitions, tracing dependencies, watching contract drift, and serving live vault state to agents with zero setup. They're complementary on the same git-synced folder. Full comparison + step-by-step install/use: docs/DESKTOP.md.

☁️ 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

❓ FAQ

Does it delete or rewrite my files? Never deletes. adopt copies by default and stamps originals; --move is opt-in. Name collisions get suffixes.

Do I need an API key? No. Classification shells out to the claude or codex CLI you already have. Neither installed → heuristics.

Do I need Obsidian? No — the vault is plain markdown and works with any viewer (Logseq, VS Code, cat). Obsidian is just the best free graph/backlink experience — and with it, _index/Dashboard.base gives you a native database UI, plus the loredex-obsidian plugin for the full in-app experience.

What if it files something wrong? It's a plain folder — move the file, done. The _index MOCs regenerate on the next route.

Why isn't my newest topic at the top of Obsidian's file tree? Obsidian sorts folders alphabetically — no setting changes that. Use _index/<project>.md (topics newest-first with dates) or the Dashboard base.

📚 Documentation

Doc What's in it
INFOGRAPHICS Full visual walkthrough of the product story with all 13 announcement-ready PNGs
USER-GUIDE Every command, lifecycle-organized, plus a guided test-drive and the multi-repo team walkthrough
VAULT-SPEC The one-page protocol: layout, frontmatter contract, link policy, provenance
ARCHITECTURE Design on one page — core modules, four shells, decisions
INTEGRATIONS BMAD + Spec Kit paste-in snippets
DESKTOP The native desktop app — install per OS, first run, every view, MCP wiring, and desktop-vs-Obsidian
loredex-obsidian The Obsidian plugin — install, settings, network disclosure

🗺️ Roadmap

  • curate — objective-driven briefs, stale/drift/orphan detection, semantic links
  • Team vaults — handoffs, shared git remote, session-start context pull
  • MCP server — agents read the vault as long-term memory
  • Obsidian plugin — loredex-obsidian: Bases dashboard, handoff badge, in-app MCP
  • Native Bases dashboard (_index/Dashboard.base)
  • Desktop app — loredex-desktop: mac/win/linux, handoff board, atlas, contracts, live sync
  • Code signing + notarization for the desktop app
  • Obsidian community directory listing
  • Semantic search over the vault
  • Cursor-native hook adapter

🛠️ Contributing

PRs welcome — start with CONTRIBUTING.md and docs/ARCHITECTURE.md (the whole design fits on one page). Good first issues are labeled good first issue.

git clone https://github.com/ahmedtawfeeq1/loredex && cd loredex
npm install && npm test

MIT © Ahmed Tawfeeq — Head of AI & Founder @ genudo.ai