A Codex plugin that gives your AI coding agent persistent, shared knowledge across every project and session.

Lore watches your sessions, learns your patterns, and whispers the right context — naming conventions, architecture decisions, past choices — before each prompt. Automatically. You just install it and code.

git clone https://github.com/yimwoo/lore.git /tmp/lore && bash /tmp/lore/install.sh

Restart Codex, open Local Plugins, find Lore, and click Install.

That's it. Start coding. Lore starts learning.

Already have a CLAUDE.md, .cursorrules, or CONVENTIONS.md? Run lore init in your project directory to import your existing rules in seconds. See Cold Start.

Every time you start a new Codex session, your agent forgets everything — your naming conventions, your architecture decisions, why you chose library A over B. You re-explain the same context every session, every project, every day.

Lore fixes this. It maintains persistent, cross-project memory and delivers it automatically:

You type: "fix the billing migration"
Your agent sees (you don't have to):
 [Lore]
 - rule: DB columns use snake_case across all services.
 - architecture: MySQL is the source of truth for billing state.
Your agent responds:
 "Since your project uses snake_case for DB columns, I'll name the
 new field payment_status_code. And I'll write directly to MySQL
 rather than going through the Redis cache."

No extra prompts. No copy-pasting context. Your agent just knows.

Most users never write a single command. Here's what happens after you install:

Sessions 1–2: Lore observes silently. It maps your files, tools, and recurring patterns.

Session 3+: Lore starts whispering. Before each prompt, it injects the most relevant context — rules, decisions, preferences — your agent picks up automatically.

Over time: Lore drafts pending knowledge from recent turns, merges repeated patterns at session start, and surfaces what needs review in a lightweight SessionStart digest.

Approved knowledge becomes permanent — shared across every future project, forever.

You always stay in control. Lore never adds knowledge to your store without your explicit approval. Suggestions stay pending until you say so. See You Control Everything.

Lore architecture diagram showing two memory tiers and four delivery layers

Lore keeps two tiers of memory:

• Project memory — per-repo session context (active files, recent errors). Short-term working memory.
• Shared knowledge — cross-project facts (domain rules, architecture decisions, preferences). Long-term memory that builds over time.

Shared knowledge reaches your agent through three runtime delivery layers:

The whisper system is the key feature. It scores each knowledge entry against your current prompt using keyword overlap, tag matching, session affinity, and recent signals — then applies repetition decay so it never nags. If nothing is relevant, it says nothing. Your agent doesn't even know Lore is there.

For a deeper dive, see the Design Overview.

Already have convention files? Lore can import them immediately:

lore init # Scan project, import found convention files interactively
lore init --yes # Auto-import all found files (scripted setup)

lore init scans for .cursorrules, CLAUDE.md, .clinerules, .windsurfrules, AGENTS.md, CONVENTIONS.md, and more. Each file is parsed into individual knowledge entries as pending suggestions for your review.

Or import specific files directly:

lore import CLAUDE.md # Import as pending entries
lore import .cursorrules --approve-all # Import and auto-approve
lore import AGENTS.md --dry-run # Preview without importing
lore import CONVENTIONS.md --kind domain_rule --tag-prefix team

Cross-project recall — You're in Project B debugging a billing service. Lore whispers that three weeks ago in Project A, you decided Postgres is the source of truth for billing state — not Redis. Without Lore, you'd spend 30 minutes rediscovering that.

Language switching — You switch between a TypeScript API and a Python ML pipeline. Lore remembers your naming conventions, preferred test frameworks, and architecture boundaries for each. It whispers the right conventions for whichever project you're in.

Team onboarding — A new teammate onboards using your shared Codex setup. Your Lore knowledge store acts as living documentation — every rule, decision, and preference your agent already knows.

Lore never adds shared knowledge automatically. Every entry requires your explicit approval.

Your knowledge store is yours. Lore earns its place by being useful, not by taking over.

Your agent can proactively search Lore for deeper context:

Bundled with the plugin install — no separate MCP configuration needed.

Most users start with lore init and let Lore learn on its own after that. For direct control, the CLI provides full management:

lore init # Scan project + import interactively
lore import CLAUDE.md # Import a specific file
lore import .cursorrules --approve-all # Import and auto-approve

lore promote \
 --kind domain_rule \
 --title "Use snake_case for DB columns" \
 --content "All database columns must use snake_case naming across services and migrations." \
 --tags "naming,database"

lore list-shared # All entries
lore list-shared --tag database # Filter by tag
lore list-shared --stale # Entries not seen in 60+ days
lore list-shared --contradictions # Entries with conflicts
lore dashboard # Full knowledge base overview

When Lore detects contradictory rules, it surfaces them at session start:

lore resolve <idA> <idB> --keep <id> # Keep one, demote other
lore resolve <idA> <idB> --scope <id> --project api # Make one project-specific
lore resolve <idA> <idB> --merge # Combine into one entry
lore history <id> # Trace supersession chain

lore demote <entry-id> --reason "migrated to camelCase"

The lore CLI is globally available after running install.sh (via npm link). If you installed manually, run npm link from ~/.codex/plugins/lore-source/ to register the command.

Prerequisites: Node.js 18+, npm

git clone https://github.com/yimwoo/lore.git /tmp/lore && bash /tmp/lore/install.sh

This clones Lore to ~/.codex/plugins/lore-source/, runs npm install, links the lore CLI globally (via npm link), registers a marketplace entry in ~/.agents/plugins/marketplace.json, and refreshes Codex's local plugin cache.

Use --local to point the marketplace at your working copy:

bash install.sh --local

git clone https://github.com/yimwoo/lore.git ~/.codex/plugins/lore-source
cd ~/.codex/plugins/lore-source
npm install
npm link # makes `lore` available on your PATH

Then add a marketplace entry to ~/.agents/plugins/marketplace.json:

{
 "name": "lore",
 "source": { "source": "local", "path": "~/.codex/plugins/lore-source" },
 "policy": { "installation": "AVAILABLE" },
 "category": "Productivity"
}

Restart Codex after installing.

Hooks are auto-discovered from .codex/hooks.json in your repo. For global use, copy to ~/.codex/hooks.json.

All data lives locally on your machine:

~/.lore/
 shared.json Shared knowledge entries
 approval-ledger.json Append-only audit trail
 conflicts.json Detected knowledge conflicts
 observations/ Per-session observation logs
 drafts/ Per-session extracted draft candidates
 consolidation-state.json SessionStart consolidation watermark
 whisper-sessions/ Per-session whisper state

Every state change writes to the ledger first — crash-safe, nothing ever hard-deleted.

bash ~/.codex/plugins/lore-source/install.sh

npm test # 624 tests
npm run test:watch # watch mode
npm run typecheck # tsc --noEmit
npm run demo # simulated session

src/
 core/ Memory store, hint engine, daemon, markdown parser, dashboard aggregator
 plugin/ SessionStart, instruction template, whisper, stop observer
 promotion/ Promote, demote, approve, draft store, consolidator, conflict detection
 extraction/ LLM provider interfaces, signal classifier
 mcp/ MCP recall tool handlers + dashboard tool
 shared/ Types, validators, semantic normalizer
 cli/ Init onboarding flow
 ui/ React sidecar component (experimental)
tests/ Vitest coverage — 624 tests across 42 files

See the Design Overview for architecture diagrams, whisper scoring details, promotion workflow, and storage layout.

rm -rf ~/.codex/plugins/lore-source # remove plugin
rm -rf ~/.lore # remove stored data (optional)

Edit ~/.agents/plugins/marketplace.json to remove the Lore entry, then restart Codex.

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

MIT