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.shRestart Codex, open Local Plugins, find Lore, and click Install.
That's it. Start coding. Lore starts learning.
Want to teach Lore rules directly right now? See Managing Knowledge.
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 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:
| Layer | When | What |
|---|---|---|
| SessionStart | Once per session | Top 5–15 stable facts, biased toward your current workspace |
| Whisper | Before each prompt | 0–4 adaptive bullets — most relevant shared knowledge, plus light high-confidence session nudges |
| MCP Recall | On demand | Deep search across all shared knowledge |
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.
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.
| Kind | What it captures | Example |
|---|---|---|
domain_rule |
Stable rules that rarely change | "All DB columns use snake_case" |
architecture_fact |
Stack and platform assumptions | "PostgreSQL is source of truth" |
decision_record |
Past decisions with rationale | "Chose Postgres over Mongo for ACID" |
user_preference |
Coding style and tool choices | "Prefer named exports over default" |
glossary_term |
Domain vocabulary | "SOR: Source of Record" |
Lore never adds shared knowledge automatically. Every entry requires your explicit approval.
| Path | How it works |
|---|---|
| SessionStart digest | Lore tells you when pending suggestions exist and points you to lore list-shared --status pending |
| Inline correction | Tell your agent "that rule is outdated" — it demotes the entry on the spot |
| CLI promotion | Power users can promote knowledge directly via CLI (no approval step needed) |
| Demotion | Soft-delete with full audit trail — nothing is ever hard-deleted |
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:
| Tool | Returns |
|---|---|
lore.recall_rules |
Domain rules and glossary terms |
lore.recall_architecture |
Architecture facts and platform assumptions |
lore.recall_decisions |
Decision records with rationale |
lore.search_knowledge |
Cross-kind freeform search |
Bundled with the plugin install — no separate MCP configuration needed.
Most users let Lore learn on its own and review pending suggestions when SessionStart flags them. If you want to seed Lore immediately — with your team's standards, onboarding rules, or existing documentation — the CLI gives you direct control.
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"That entry is now in your shared knowledge store — every future session, across every project.
lore list-sharedlore demote <entry-id> --reason "migrated to camelCase"The
loreCLI is available after runninginstall.sh. If you installed manually, runnpm linkfrom~/.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.shThis clones Lore to ~/.codex/plugins/lore-source/, runs npm install, 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 --localgit clone https://github.com/yimwoo/lore.git ~/.codex/plugins/lore-source
cd ~/.codex/plugins/lore-source
npm installThen 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.
| Hook | Purpose |
|---|---|
SessionStart |
Runs bounded consolidation, injects shared knowledge, initializes whisper state |
UserPromptSubmit |
Whispers relevant shared knowledge before each prompt |
Stop (async) |
Updates session context and drafts candidate knowledge after each turn |
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
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.shnpm test # 339 tests
npm run test:watch # watch mode
npm run typecheck # tsc --noEmit
npm run demo # simulated sessionsrc/
core/ Memory store, hint engine, daemon
plugin/ SessionStart, instruction template, whisper, stop observer
promotion/ Promote, demote, approve, draft store, consolidator
mcp/ MCP recall tool handlers
shared/ Types and validators
ui/ React sidecar component (experimental)
tests/ Vitest coverage for core, plugin, CLI, and promotion flows
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