{
  "markdown": "# 📖 Lore\n\n### Shared, full-fidelity, session history for every AI agent you use.\n\n**Any Agent. Any Session. Any Turn. Anytime.**\n\nThe session you ran in Claude Code this morning, Openclaw can pull up this afternoon.\nThe debugging thread Cursor worked through last week, Hermes can read\nlike it was sitting right there. Lore gives all of your coding agents one shared\nmemory: across every tool, across every session, and it never expires.\n\nThat is the part most \"agent memory\" misses. Other tools remember things for one\nagent, inside one app. Lore makes every session any of your agents has ever had\nsearchable by any other agent, anytime. What Codex figured out, Claude Code knows.\nWhat you solved on Tuesday is one search away on Friday, in whatever agent you\nhappen to be in.\n\nAnd yes, it survives compaction. When a context window fills up and compacts, the\nwork isn't gone, it's sitting right there on disk. Lore just makes it reachable\nagain, fully searchable, right where your agents work. Local, private, and yours\nforever.\n\n\n\nhttps://github.com/user-attachments/assets/b5c0f077-47da-4502-bf78-2ce08abf034f\n\n*Inspired by [RLM](https://arxiv.org/abs/2512.24601)*\n\n## v0.2.0 release\n\nThis release turns Lore from a search box over old transcripts into a small\nworkflow substrate for agents that have to continue real work:\n\n- **Schema 5 write support.** Current installs can read and write the live store\n  again. `lore status --json` reports both `schemaVersion` and\n  `supportedSchemaVersion`, so stale global installs are obvious before sync,\n  index, or push writes fail.\n- **Freshness checks.** `lore status` tells an agent whether a source/project\n  window is ready, missing, stale, or possibly unsynced before it writes a brief\n  or handoff from incomplete memory.\n- **Live detected-source sync.** `lore sync <source>` indexes a detected active\n  transcript tree incrementally. This covers `codex` (`~/.codex/sessions`, with\n  archived sessions as a compatibility fallback) and `claude-code`\n  (`~/.claude/projects`) without forcing agents to remember raw paths.\n- **Workflow skills.** The npm package now ships `lore-recall`, `lore-brief`,\n  `lore-handoff`, and `lore-dev-verification` alongside the base `lore` skill.\n  They include references, examples, eval specs, validators, and committed test\n  reports.\n- **Package smoke proof.** `npm run package:smoke` builds, packs, unpacks, and\n  validates the real tarball so README, help text, skill folders, executable\n  mode, and package metadata are checked together.\n\nAlready installed? Refresh the global command before testing any schema or sync\nbehavior:\n\n```bash\nnpm install -g @jordanhindo/lore@latest\nlore help\nlore status --json\n```\n\nIf your shell cached the old path, open a new terminal or run `hash -r` and retry\n`lore help`.\n\n## ✨ Why you'll want it\n\n- 🔀 **One memory, every agent.** Claude Code, Codex, openclaw, Cursor, and\n  Hermes histories all land in one store (separate from their own /.<agent> stores), and any MCP client reads it. A session\n  in one agent is instantly readable by all the others. What Codex figures out,\n  Claude Code knows.\n- 🧠 **It outlives the context window.** Compaction stops meaning amnesia.\n  Last week's reasoning is one search away.\n- 🔍 **Search that speaks code.** `getUserById`, `foo.bar.ts`, and `trust-metadata`\n  stay findable as whole words, not shredded into noise.\n- 🔒 **Local by default.** Everything lives at `~/.lore/lore.db` on your\n  machine. Nothing phones home. Ever.\n\n## 🚀 Quick start (paste this into your agent)\n\nLore sets itself up. Drop the blurb below into any coding agent. It installs\nLore, indexes your own history, and proves search works before it calls itself\ndone. It is server-free by default, with no MCP registration required.\n\n```\nSet up Lore (full-fidelity session memory) for yourself. Install it with\n`npm install -g @jordanhindo/lore@latest`, then run `lore setup` to index my\nhistory and self-verify. Prove it by running `lore search` for a word from\na past session and showing me a hit. The MCP server is optional: only\nregister it (`lore serve`) if you specifically want MCP tool calls instead\nof the CLI; if you do, tell me the reload step I have to do.\n```\n\nThe deterministic recipe the agent follows lives in\n[`AGENT-ONBOARD.md`](AGENT-ONBOARD.md), which keeps MCP registration as an\noptional step. Prefer the skill instead? `npx skills add jordanhindo/lore`\n(below) drops in the self-bootstrapping `lore` skill, which does all of this the\nnext time you ask it to recall something.\n\n\n## 🛠️ Install it yourself\n\n**Recommended: install the skill. It sets up the rest.**\n\n```bash\nnpx skills add jordanhindo/lore\n```\n\nThis drops the bundled **`lore` skill** into your agent (`~/.claude/skills/`). The\nskill is self-bootstrapping: the next time you ask your agent to \"remember\" /\n\"recall\" something or to \"set up lore\", it reads its own `references/setup/index.md`,\ninstalls the `lore` CLI, indexes your history, and proves search works. No MCP\nserver required. One command installs the whole thing.\n\n**Or install the CLI directly:**\n\n```bash\nnpm install -g @jordanhindo/lore@latest   # puts the `lore` command on your PATH\n```\n\nRequires Node 22+. That's the whole install. `lore setup` takes it from here. If\n`npm install` chokes on `better-sqlite3`, or `lore` isn't found afterward, the\n[Troubleshooting](AGENT-ONBOARD.md#troubleshooting-when-step-1-or-2-fails)\nsection has you covered, Windows included.\n\n### Upgrade the global CLI\n\nThe global `lore` command is just an npm binary shim. If you were running an old\npackage, update it before you trust `lore sync`, `lore index`, or `lore push`:\n\n```bash\nnpm install -g @jordanhindo/lore@latest\nlore help\nlore status --json\n```\n\nIf `lore status --json` shows a store `schemaVersion` higher than\n`supportedSchemaVersion`, your command is still stale. Reinstall the package,\nopen a fresh shell if needed, then rerun `lore status --json`.\n\n### From source\n\nCloning is for contributors, or for writing a new adapter (which needs the\nsource tree):\n\n```bash\ngit clone https://github.com/jordanhindo/lore && cd lore\nnpm install\nnpm run build\nnpm link        # optional: puts `lore` on your PATH\n```\n\n## 📥 Backfill your history\n\n`lore setup` is the fast path. It sniffs out the harnesses on your machine,\nindexes each one, checks that search works, and prints how to wire Lore into\nyour MCP client.\n\n```bash\nlore setup\n```\n\nWant finer control? Point `lore index` at a transcript directory. For Claude\nCode that's `~/.claude/projects`:\n\n```bash\nlore index ~/.claude/projects              # primary transcripts\nlore index ~/.claude/projects --subagents  # include subagent transcripts\nlore index ~/.claude/projects --no-redact  # keep credentials verbatim (see Privacy)\n```\n\nOther harnesses come in with `--source`. Codex, openclaw, Cursor, and Hermes are\nall built in:\n\n```bash\nlore index ~/.codex/sessions --source codex\nlore index ~/.openclaw/sessions --source openclaw\nlore index ~/.cursor --source cursor     # reads Cursor's SQLite state store\nlore index ~/.hermes --source hermes     # reads Hermes's SQLite state store\n```\n\nCursor and Hermes keep their history in a SQLite database rather than JSONL\nfiles; point `lore index` at the directory and the adapter reads the store\ndirectly. Current sampled Cursor rows expose `toolResults` fields but only empty\narrays, so the Cursor adapter indexes text only and fabricates no tool calls.\n\nRe-run any of these whenever. Unchanged files get skipped, so repeat runs are\ncheap.\n\nSome harnesses write transcript trees instead of emitting Lore-compatible hook\npayloads. For manual active-session catch-up, use the incremental sync command:\n\n```bash\nlore sync codex\nlore sync claude-code\nlore sync hermes\n```\n\n`codex` sync indexes `~/.codex/sessions` incrementally, with\n`~/.codex/archived_sessions` only as a compatibility fallback. `claude-code`\nsync indexes `~/.claude/projects` incrementally, including subagent\ntranscripts. `hermes` sync indexes `~/.hermes` incrementally.\n\nFor cron, launchd, Task Scheduler, or any unattended timer, use the bundled\nlock-protected wrapper instead of raw `lore sync` so multiple source jobs do not\nwrite `~/.lore/lore.db` at the same time:\n\n```bash\n./scripts/lore-sync-once.sh codex\n./scripts/lore-sync-once.sh claude-code\n./scripts/lore-sync-once.sh hermes\n```\n\n## 💻 Recall from the CLI, no server required\n\nYou don't need the MCP server to use Lore. The `lore` command opens the SQLite\nstore directly, so **search, read-back, navigation, and writing all work\nserver-free** anywhere you have a shell. The MCP server below is just one more\nreader of the same store; nothing here depends on it.\n\nThe loop is always the same: **drill down, never dump.** A session can be millions\nof tokens, so you never page a whole one into context. Search broadly, take the\nreal ids it hands back (you never invent one), then spend them:\n\n```bash\nlore search \"fts tokenizer\" --relevant     # → hits, each leading with a message + session id\nlore get <message-id> --full               # read that one message in full\nlore context <message-id>                  # 5 before / 5 after, anchor flagged\nlore session <session-id> --around <message-id>   # jump to that spot, read forward\n```\n\nOther commands round out the loop: `lore status` (freshness/health),\n`lore sessions` (recent conversations), `lore timeline` (activity by day/hour),\nand `lore push` (add a live session from a JSON batch on stdin). Add `--json` to\nany of them for a machine-readable envelope.\nEvery search filter the MCP tools accept works here too (`--project`, `--source`,\n`--session`, `--branch`, `--agent`, `--skill`, `--tool`, `--role`, `--model`,\n`--since`, `--until`, `--limit`).\n\nBefore asking for a current brief or handoff, check freshness:\n\n```bash\nlore status --json --source codex --project \"$PWD\"\n```\n\n`schemaVersion` and `supportedSchemaVersion` tell you whether this build can\nwrite to the store. Read-only search may still work against a newer compatible\nstore, but sync/index/push only run when the installed build supports the store\nschema. In a source checkout, run `npm run build` before trusting the global\n`lore` shim. For npm installs, run\n`npm install -g @jordanhindo/lore@latest` and check `lore status --json` again.\n\n**CLI ⇄ MCP parity is proven, not asserted.** Each `lore … --json` envelope is\nbyte-for-byte identical to the matching MCP tool's response, verified by a parity\ntest suite that runs both paths against one shared fixture store. So the CLI is a\nfaithful stand-in for the server:\n\n| task | CLI | MCP tool | `--json` envelope |\n|------|-----|----------|-------------------|\n| keyword search | `lore search` | `search_memory` | `{ count, hits }` |\n| recency-blended search | `lore search --relevant` | `find_relevant` | `{ count, hits }` |\n| one message | `lore get` | `get_message` | detail obj / `{ error, message_id }` |\n| neighbors | `lore context` | `get_context` | `{ messages }` |\n| session page | `lore session` | `get_session` | `{ messages, nextCursor }` |\n| session list | `lore sessions` | `list_sessions` | `{ count, sessions }` |\n| activity | `lore timeline` | `timeline` | `{ buckets }` |\n| status/freshness | `lore status` | `status` | status envelope |\n| write | `lore push` | `push` | result / `{ error, detail }` |\n\nThe bundled **`lore` skill** (`skills/lore/`) teaches an agent to drive this whole\nloop: when to search, which id to spend, and how to drill down instead of\ndumping. It's self-bootstrapping: its `references/setup/index.md` covers getting history\nindexed in the first place (install, index/backfill a harness, write an adapter,\nor push), so one `npx skills add jordanhindo/lore` installs the whole thing.\n\n\n## Agent Workflow Skills\n\nThe low-level `skills/lore/` skill teaches agents how to install Lore, index\ntranscripts, search memory, drill into message ids, and use the MCP server when\na harness supports it. The workflow pack sits above that substrate:\n\n- `lore:recall` maps to `skills/lore-recall/`. It plans bounded retrieval, checks `lore status --json`, labels freshness, drills into context windows, and emits cited evidence packets instead of transcript dumps.\n- `lore:brief` maps to `skills/lore-brief/`. It defaults to the rolling last 24 hours, summarizes completed/open work, and proposes follow-up skills, jobs, issues, fixes, tasks, memory cards, or wiki updates without performing them.\n- `lore:handoff` maps to `skills/lore-handoff/`. It creates compact continuation packets with verified/open/stale/risky sections, artifacts, shared proposal objects, memory-card candidates, contradiction candidates, and next actions.\n- `lore:dev-verification` maps to `skills/lore-dev-verification/`. It is the project-specific verification gate for Lore repo changes: CLI/MCP parity, store compatibility, adapter fidelity, privacy/destructive-memory behavior, package smoke, and workflow-skill eval proof.\n\nThese are installable skill bundles, not one-file prompt snippets. Each workflow\nskill includes `SKILL.md`, references, examples, eval specs, validator scripts\nwhere structure is deterministic, and `evals/test-report.md`. A workflow skill is\nnot complete until its test report proves the eval/review pass ran and the bundle\nvalidator passes.\n\nThere is no universal plugin wrapper in this release. A future plugin could\nbundle names such as `lore:recall`, `lore:brief`, and `lore:handoff`, but today\nthe shipped surface is the package `skills/` tree plus the `lore` CLI/MCP\nsubstrate. Workflow skills may propose actions; they must not create jobs, edit\nprompts, update wiki pages, create tasks, modify code, or run destructive memory\noperations unless the user explicitly asks for that next step.\n\nWhen you change any part of this pack, update the matching surface too: CLI help,\nREADME, `AGENT-ONBOARD.md`, `skills/lore`, workflow skill docs, validators,\nexamples, eval reports, and package smoke checks should move together.\n\nPackaging proof lives in:\n\n```bash\nnpm run package:smoke\n```\n\nThat smoke builds the CLI, preserves executable mode for `dist/cli/lore.js`,\nvalidates package dry-run metadata, packs a real tarball, reads the workflow\nskill folders from the packaged tree, checks non-hollow test-report headings, and\nverifies the packaged CLI help can run with dependencies present.\n\n## 🔌 Serve it to your client\n\n`lore serve` starts the MCP server over stdio. Point any MCP client at it.\n\n**Claude Code** (add to `~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"lore\": { \"command\": \"lore\", \"args\": [\"serve\"] }\n  }\n}\n```\n\n**Cursor / Cline** and friends: add an stdio server entry with the same\n`command` / `args` shape in the client's MCP config.\n\n### What your agent can do\n\n| Tool            | What it does                                                           |\n| --------------- | --------------------------------------------------------------------- |\n| `status`        | Store health/freshness, schema version, source/project scoped counts. |\n| `search_memory` | Keyword search across every transcript, ranked by bm25, with filters. |\n| `find_relevant` | Like `search_memory`, but blends relevance with recency.              |\n| `get_message`   | Fetch one message by id (`full=true` returns the un-elided text).     |\n| `get_context`   | The neighbor window around an anchor message.                         |\n| `get_session`   | One logical session as a folded, paginated timeline.                  |\n| `list_sessions` | Session rollups (counts, first / last activity), filterable.          |\n| `timeline`      | Bucketed activity over time, by day or hour.                          |\n| `push`          | Write one normalized live JSON batch, matching CLI `lore push`.       |\n\nEvery search tool takes the same dimension filters: `project`, `branch`,\n`source`, `agent`, `skill`, `tool`, `role`, `model`, `since`, `until`, `limit`.\n\n### What a search returns\n\nYour agent calls `search_memory` with a query (plus any filters) and gets back a\ncount and a ranked list of hits. Each hit carries the matched text and full\nprovenance, so the agent knows _where_ the memory came from and can pull the rest\nwith `get_message`:\n\n```jsonc\n// search_memory({ query: \"fts tokenizer\", source: \"claude-code\", limit: 2 })\n{\n  \"count\": 2,\n  \"hits\": [\n    {\n      \"messageId\": \"9f3c…a71b\",          // synthetic, stable across re-index\n      \"sessionId\": \"0c1d2e3f-…\",\n      \"sourceFileId\": \"claude-code:…\",\n      \"source\": \"claude-code\",            // harness namespace the hit came from\n      \"role\": \"assistant\",\n      \"timestamp\": \"2026-06-05T18:22:41.103Z\",\n      \"project\": \"/Users/you/lore\",\n      \"branch\": \"main\",\n      \"model\": \"claude-opus-4\",\n      \"agent\": null,\n      \"score\": 11.27,                       // higher is a better match (bm25)\n      \"text\": \"Switched the FTS5 tokenizer to unicode61 with tokenchars '_-.' so getUserById and foo.bar.ts stay whole…\",\n      \"textTruncated\": false\n    }\n    // …one more hit\n  ]\n}\n```\n\nLong messages come back elided with a marker telling the agent how to fetch the\nfull text via `get_message(message_id, full=true)`, so one giant transcript can\nnever blow the context window.\n\n## 🪄 Survive compaction\n\nCompaction is the moment memory matters most, so catch fresh session content\nbefore it disappears from the active context. The exact hook differs by harness:\nClaude Code can call `lore hook` from `PreCompact` / `SessionEnd` when a hook\npayload is available, or `lore sync claude-code` for manual catch-up when only\nthe transcript tree needs freshening. Timers should call\n`scripts/lore-sync-once.sh claude-code` so the shared store write is locked.\nCodex should use its notify wrapper or `scripts/lore-sync-once.sh codex` from a\ntimer because it writes a session tree rather than a `transcript_path` hook\npayload.\n\nThe skill setup references carry the exact recipes:\n[`skills/lore/references/setup/claude-code-hooks.md`](skills/lore/references/setup/claude-code-hooks.md),\n[`skills/lore/references/setup/codex-hooks.md`](skills/lore/references/setup/codex-hooks.md),\nand\n[`skills/lore/references/setup/other-harness-hooks.md`](skills/lore/references/setup/other-harness-hooks.md).\n\n## 🧩 Bring your own harness\n\nDon't see your agent on the list? `lore sample <transcript-dir>` summarizes its\non-disk format. It recognizes JSONL, SQLite databases (read via the file header,\nnever by loading the DB), and whole-file JSON, so you can see an unknown\nharness's shape before writing anything. The bundled **`lore` skill**'s\n`references/setup/index.md` (`skills/lore/references/setup/index.md`) walks an agent from\n\"installed\" to \"my sessions are searchable,\" including writing and proving a new\nadapter, or using the live `push` path when a harness keeps no files at all.\n`push` is **data only**: it validates every record at the boundary and never\nreceives or executes code.\n\n## 🔒 Privacy\n\n- The store is local (`~/.lore/lore.db`), lives outside any repo, and `*.db`\n  is gitignored. Move it with `LORE_DB`.\n- **Credentials are redacted by default.** A conservative scrubber runs over\n  message text and tool payloads before anything is written (OpenAI / GitHub /\n  AWS / Slack keys, Bearer tokens, PEM private-key blocks). Everything else is\n  kept verbatim. It's your own memory. Treat the scrubber as a safety net, not\n  a guarantee.\n- **Opt out with `--no-redact`** on `lore index` / `lore hook` / `lore setup`\n  if you really want credentials stored verbatim too.\n- **Remove memory you didn't want kept.** `lore forget` deletes a session or a\n  project (point-in-time); `lore exclude` deletes a project and bars all future\n  captures from it. Both print an exact-scope preview and only act when you add\n  `--confirm`, and both write a tombstone so re-indexing can't resurrect the\n  data. See the `lore` skill for the full preview-then-confirm protocol.\n\n## 🧬 How it works under the hood\n\n- **One shared store, many harnesses.** Each harness writes into its own `source`\n  namespace (`claude-code`, `codex`, `openclaw`, `cursor`, `hermes`). Any MCP\n  client can read everyone's history.\n- **Three IDs.** A `source_file_id` is a physical transcript file (the unit of\n  ingestion and the resume watermark). A `session_id` is a logical session shared\n  across a primary file and its subagent files. Each message gets a synthetic\n  `message_id = hash(source_file_id + uuid + seq)` because raw uuids collide.\n- **Incremental by construction.** A per-file watermark skips unchanged files,\n  appends only new tails, and fully re-indexes rewritten ones. Re-running a\n  backfill over thousands of transcripts only touches what changed.\n- **Code-aware search.** The FTS5 tokenizer keeps identifiers and paths whole, so\n  the things you actually search for stay searchable.\n\n## ⚙️ Environment\n\n| Var                | Default               | Meaning                              |\n| ------------------ | --------------------- | ------------------------------------ |\n| `LORE_DB`        | `~/.lore/lore.db` | Store location.                      |\n| `LORE_LOG_LEVEL` | `info`                | `debug` / `info` / `warn` / `error`. |\n\n## 👷 Development\n\n```bash\nnpm run check   # typecheck + lint + format + test\nnpm run test:watch\n```\n\nLicense: MIT.\n",
  "bytes": 21236,
  "sha": "778144841fb9ad39a4b61ad294bcf0319b0d632ad146b1f921b4ac1a61863af1",
  "repo_slug": "jordanhindo/lore",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jordanhindo_lore_17959eb3/readme"
}