{"id":47701522,"url":"https://github.com/yimwoo/lore","last_synced_at":"2026-04-03T19:01:23.655Z","repository":{"id":347608525,"uuid":"1194242440","full_name":"yimwoo/lore","owner":"yimwoo","description":"Persistent cross-project memory for Codex — rules, decisions, and context that follow you.","archived":false,"fork":false,"pushed_at":"2026-03-29T20:45:10.000Z","size":632,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T03:43:51.932Z","etag":null,"topics":["ai-coding-assistant","codex-plugin","context-management","cross-project","developer-experience","developer-tool","mcp","mcp-server","memory-knowledge-management","productivity","second-brain"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yimwoo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-28T04:56:01.000Z","updated_at":"2026-03-29T20:45:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yimwoo/lore","commit_stats":null,"previous_names":["yimwoo/lore"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/yimwoo/lore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Flore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Flore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Flore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Flore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yimwoo","download_url":"https://codeload.github.com/yimwoo/lore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Flore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31371612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-coding-assistant","codex-plugin","context-management","cross-project","developer-experience","developer-tool","mcp","mcp-server","memory-knowledge-management","productivity","second-brain"],"created_at":"2026-04-02T17:19:38.038Z","updated_at":"2026-04-03T19:01:23.579Z","avatar_url":"https://github.com/yimwoo.png","language":"TypeScript","readme":"# Lore — Cross-Project Memory for Codex\n\n**A Codex plugin that gives your AI coding agent persistent, shared knowledge across every project and session.**\n\nLore 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.\n\n---\n\n## Quick Start\n\n```bash\ngit clone https://github.com/yimwoo/lore.git /tmp/lore \u0026\u0026 bash /tmp/lore/install.sh\n```\n\nRestart Codex, open **Local Plugins**, find **Lore**, and click **Install**.\n\n**That's it. Start coding. Lore starts learning.**\n\n\u003e 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](#cold-start-instant-setup).\n\n---\n\n## What Lore Does\n\nEvery 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.\n\nLore fixes this. It maintains persistent, cross-project memory and delivers it automatically:\n\n```text\nYou type: \"fix the billing migration\"\n\nYour agent sees (you don't have to):\n  [Lore]\n  - rule: DB columns use snake_case across all services.\n  - architecture: MySQL is the source of truth for billing state.\n\nYour agent responds:\n  \"Since your project uses snake_case for DB columns, I'll name the\n   new field payment_status_code. And I'll write directly to MySQL\n   rather than going through the Redis cache.\"\n```\n\nNo extra prompts. No copy-pasting context. Your agent just *knows*.\n\n---\n\n## How Lore Learns\n\nMost users never write a single command. Here's what happens after you install:\n\n**Sessions 1–2:** Lore observes silently. It maps your files, tools, and recurring patterns.\n\n**Session 3+:** Lore starts whispering. Before each prompt, it injects the most relevant context — rules, decisions, preferences — your agent picks up automatically.\n\n**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.\n\nApproved knowledge becomes permanent — shared across every future project, forever.\n\n\u003e **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](#you-control-everything).\n\n---\n\n## How It Works\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/lore-architecture.svg\" alt=\"Lore architecture diagram showing two memory tiers and four delivery layers\" width=\"680\" /\u003e\n\u003c/p\u003e\n\nLore keeps two tiers of memory:\n\n- **Project memory** — per-repo session context (active files, recent errors). Short-term working memory.\n- **Shared knowledge** — cross-project facts (domain rules, architecture decisions, preferences). Long-term memory that builds over time.\n\nShared knowledge reaches your agent through three runtime delivery layers:\n\n| Layer | When | What |\n|---|---|---|\n| **SessionStart** | Once per session | Top 5–15 stable facts, biased toward your current workspace |\n| **Whisper** | Before each prompt | 0–4 adaptive bullets — most relevant shared knowledge, plus light high-confidence session nudges |\n| **MCP Recall** | On demand | Deep search across all shared knowledge |\n\nThe **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.\n\nFor a deeper dive, see the [Design Overview](docs/design.md).\n\n---\n\n## Cold Start — Instant Setup\n\nAlready have convention files? Lore can import them immediately:\n\n```bash\nlore init                    # Scan project, import found convention files interactively\nlore init --yes              # Auto-import all found files (scripted setup)\n```\n\n`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.\n\nOr import specific files directly:\n\n```bash\nlore import CLAUDE.md                      # Import as pending entries\nlore import .cursorrules --approve-all     # Import and auto-approve\nlore import AGENTS.md --dry-run            # Preview without importing\nlore import CONVENTIONS.md --kind domain_rule --tag-prefix team\n```\n\n---\n\n## Real-World Examples\n\n**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.\n\n**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.\n\n**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.\n\n---\n\n## Shared Knowledge Kinds\n\n| Kind | What it captures | Example |\n|---|---|---|\n| `domain_rule` | Stable rules that rarely change | \"All DB columns use snake_case\" |\n| `architecture_fact` | Stack and platform assumptions | \"PostgreSQL is source of truth\" |\n| `decision_record` | Past decisions with rationale | \"Chose Postgres over Mongo for ACID\" |\n| `user_preference` | Coding style and tool choices | \"Prefer named exports over default\" |\n| `glossary_term` | Domain vocabulary | \"SOR: Source of Record\" |\n\n---\n\n## You Control Everything\n\nLore **never** adds shared knowledge automatically. Every entry requires your explicit approval.\n\n| Path | How it works |\n|---|---|\n| **SessionStart digest** | Lore tells you when pending suggestions exist and points you to `lore list-shared --status pending` |\n| **Inline correction** | Tell your agent \"that rule is outdated\" — it demotes the entry on the spot |\n| **CLI promotion** | Power users can promote knowledge directly via CLI (no approval step needed) |\n| **Demotion** | Soft-delete with full audit trail — nothing is ever hard-deleted |\n\nYour knowledge store is yours. Lore earns its place by being useful, not by taking over.\n\n---\n\n## MCP Recall Tools\n\nYour agent can proactively search Lore for deeper context:\n\n| Tool | Returns |\n|---|---|\n| `lore.recall_rules` | Domain rules and glossary terms |\n| `lore.recall_architecture` | Architecture facts and platform assumptions |\n| `lore.recall_decisions` | Decision records with rationale |\n| `lore.search_knowledge` | Cross-kind freeform search |\n| `lore.dashboard` | Knowledge base overview (counts, tags, health) |\n\nBundled with the plugin install — no separate MCP configuration needed.\n\n---\n\n## Managing Knowledge\n\nMost users start with `lore init` and let Lore learn on its own after that. For direct control, the CLI provides full management:\n\n### Import existing conventions\n\n```bash\nlore init                                   # Scan project + import interactively\nlore import CLAUDE.md                       # Import a specific file\nlore import .cursorrules --approve-all      # Import and auto-approve\n```\n\n### Promote a rule manually\n\n```bash\nlore promote \\\n  --kind domain_rule \\\n  --title \"Use snake_case for DB columns\" \\\n  --content \"All database columns must use snake_case naming across services and migrations.\" \\\n  --tags \"naming,database\"\n```\n\n### See what Lore knows\n\n```bash\nlore list-shared                            # All entries\nlore list-shared --tag database             # Filter by tag\nlore list-shared --stale                    # Entries not seen in 60+ days\nlore list-shared --contradictions           # Entries with conflicts\nlore dashboard                              # Full knowledge base overview\n```\n\n### Resolve conflicts\n\nWhen Lore detects contradictory rules, it surfaces them at session start:\n\n```bash\nlore resolve \u003cidA\u003e \u003cidB\u003e --keep \u003cid\u003e        # Keep one, demote other\nlore resolve \u003cidA\u003e \u003cidB\u003e --scope \u003cid\u003e --project api  # Make one project-specific\nlore resolve \u003cidA\u003e \u003cidB\u003e --merge            # Combine into one entry\nlore history \u003cid\u003e                           # Trace supersession chain\n```\n\n### Remove outdated knowledge\n\n```bash\nlore demote \u003centry-id\u003e --reason \"migrated to camelCase\"\n```\n\n\u003e 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.\n\n---\n\n## Installation\n\n**Prerequisites:** Node.js 18+, npm\n\n```bash\ngit clone https://github.com/yimwoo/lore.git /tmp/lore \u0026\u0026 bash /tmp/lore/install.sh\n```\n\nThis 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.\n\n### For Contributors\n\nUse `--local` to point the marketplace at your working copy:\n\n```bash\nbash install.sh --local\n```\n\n### Manual Installation\n\n```bash\ngit clone https://github.com/yimwoo/lore.git ~/.codex/plugins/lore-source\ncd ~/.codex/plugins/lore-source\nnpm install\nnpm link          # makes `lore` available on your PATH\n```\n\nThen add a marketplace entry to `~/.agents/plugins/marketplace.json`:\n\n```json\n{\n  \"name\": \"lore\",\n  \"source\": { \"source\": \"local\", \"path\": \"~/.codex/plugins/lore-source\" },\n  \"policy\": { \"installation\": \"AVAILABLE\" },\n  \"category\": \"Productivity\"\n}\n```\n\nRestart Codex after installing.\n\n### Hooks\n\n| Hook | Purpose |\n|---|---|\n| `SessionStart` | Runs bounded consolidation, injects shared knowledge, initializes whisper state |\n| `UserPromptSubmit` | Whispers relevant shared knowledge before each prompt |\n| `Stop` (async) | Updates session context and drafts candidate knowledge after each turn |\n\nHooks are auto-discovered from `.codex/hooks.json` in your repo. For global use, copy to `~/.codex/hooks.json`.\n\n### Storage\n\nAll data lives locally on your machine:\n\n```text\n~/.lore/\n  shared.json              Shared knowledge entries\n  approval-ledger.json     Append-only audit trail\n  conflicts.json           Detected knowledge conflicts\n  observations/            Per-session observation logs\n  drafts/                  Per-session extracted draft candidates\n  consolidation-state.json SessionStart consolidation watermark\n  whisper-sessions/        Per-session whisper state\n```\n\nEvery state change writes to the ledger first — crash-safe, nothing ever hard-deleted.\n\n### Updating\n\n```bash\nbash ~/.codex/plugins/lore-source/install.sh\n```\n\n---\n\n## Development\n\n```bash\nnpm test            # 624 tests\nnpm run test:watch  # watch mode\nnpm run typecheck   # tsc --noEmit\nnpm run demo        # simulated session\n```\n\n### Project Structure\n\n```text\nsrc/\n  core/               Memory store, hint engine, daemon, markdown parser, dashboard aggregator\n  plugin/             SessionStart, instruction template, whisper, stop observer\n  promotion/          Promote, demote, approve, draft store, consolidator, conflict detection\n  extraction/         LLM provider interfaces, signal classifier\n  mcp/                MCP recall tool handlers + dashboard tool\n  shared/             Types, validators, semantic normalizer\n  cli/                Init onboarding flow\n  ui/                 React sidecar component (experimental)\ntests/                Vitest coverage — 624 tests across 42 files\n```\n\n---\n\n## Design\n\nSee the [Design Overview](docs/design.md) for architecture diagrams, whisper scoring details, promotion workflow, and storage layout.\n\n---\n\n## Uninstalling\n\n```bash\nrm -rf ~/.codex/plugins/lore-source     # remove plugin\nrm -rf ~/.lore                           # remove stored data (optional)\n```\n\nEdit `~/.agents/plugins/marketplace.json` to remove the Lore entry, then restart Codex.\n\n---\n\n## Contributing\n\nContributions are welcome. Please open an issue first to discuss what you'd like to change.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyimwoo%2Flore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyimwoo%2Flore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyimwoo%2Flore/lists"}