The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Lore listing page.
Any Agent. Any Session. Any Turn. Anytime.
The session you ran in Claude Code this morning, Openclaw can pull up this afternoon. The debugging thread Cursor worked through last week, Hermes can read like it was sitting right there. Lore gives all of your coding agents one shared memory: across every tool, across every session, and it never expires.
That is the part most "agent memory" misses. Other tools remember things for one agent, inside one app. Lore makes every session any of your agents has ever had searchable by any other agent, anytime. What Codex figured out, Claude Code knows. What you solved on Tuesday is one search away on Friday, in whatever agent you happen to be in.
And yes, it survives compaction. When a context window fills up and compacts, the work isn't gone, it's sitting right there on disk. Lore just makes it reachable again, fully searchable, right where your agents work. Local, private, and yours forever.
https://github.com/user-attachments/assets/b5c0f077-47da-4502-bf78-2ce08abf034f
Inspired by RLM
This release turns Lore from a search box over old transcripts into a small workflow substrate for agents that have to continue real work:
lore status --json reports both schemaVersion and
supportedSchemaVersion, so stale global installs are obvious before sync,
index, or push writes fail.lore status tells an agent whether a source/project
window is ready, missing, stale, or possibly unsynced before it writes a brief
or handoff from incomplete memory.lore sync <source> indexes a detected active
transcript tree incrementally. This covers codex (~/.codex/sessions, with
archived sessions as a compatibility fallback) and claude-code
(~/.claude/projects) without forcing agents to remember raw paths.lore-recall, lore-brief,
lore-handoff, and lore-dev-verification alongside the base lore skill.
They include references, examples, eval specs, validators, and committed test
reports.npm run package:smoke builds, packs, unpacks, and
validates the real tarball so README, help text, skill folders, executable
mode, and package metadata are checked together.Already installed? Refresh the global command before testing any schema or sync behavior:
If your shell cached the old path, open a new terminal or run hash -r and retry
lore help.
getUserById, foo.bar.ts, and trust-metadata
stay findable as whole words, not shredded into noise.~/.lore/lore.db on your
machine. Nothing phones home. Ever.Lore sets itself up. Drop the blurb below into any coding agent. It installs Lore, indexes your own history, and proves search works before it calls itself done. It is server-free by default, with no MCP registration required.
The deterministic recipe the agent follows lives in
AGENT-ONBOARD.md, which keeps MCP registration as an
optional step. Prefer the skill instead? npx skills add jordanhindo/lore
(below) drops in the self-bootstrapping lore skill, which does all of this the
next time you ask it to recall something.
Recommended: install the skill. It sets up the rest.
This drops the bundled lore skill into your agent (~/.claude/skills/). The
skill is self-bootstrapping: the next time you ask your agent to "remember" /
"recall" something or to "set up lore", it reads its own references/setup/index.md,
installs the lore CLI, indexes your history, and proves search works. No MCP
server required. One command installs the whole thing.
Or install the CLI directly:
Requires Node 22+. That's the whole install. lore setup takes it from here. If
npm install chokes on better-sqlite3, or lore isn't found afterward, the
Troubleshooting
section has you covered, Windows included.
The global lore command is just an npm binary shim. If you were running an old
package, update it before you trust lore sync, lore index, or lore push:
If lore status --json shows a store schemaVersion higher than
supportedSchemaVersion, your command is still stale. Reinstall the package,
open a fresh shell if needed, then rerun lore status --json.
Cloning is for contributors, or for writing a new adapter (which needs the source tree):
lore setup is the fast path. It sniffs out the harnesses on your machine,
indexes each one, checks that search works, and prints how to wire Lore into
your MCP client.
Want finer control? Point lore index at a transcript directory. For Claude
Code that's ~/.claude/projects:
Other harnesses come in with --source. Codex, openclaw, Cursor, and Hermes are
all built in:
Cursor and Hermes keep their history in a SQLite database rather than JSONL
files; point lore index at the directory and the adapter reads the store
directly. Current sampled Cursor rows expose toolResults fields but only empty
arrays, so the Cursor adapter indexes text only and fabricates no tool calls.
Re-run any of these whenever. Unchanged files get skipped, so repeat runs are cheap.
Some harnesses write transcript trees instead of emitting Lore-compatible hook payloads. For manual active-session catch-up, use the incremental sync command:
codex sync indexes ~/.codex/sessions incrementally, with
~/.codex/archived_sessions only as a compatibility fallback. claude-code
sync indexes ~/.claude/projects incrementally, including subagent
transcripts. hermes sync indexes ~/.hermes incrementally.
For cron, launchd, Task Scheduler, or any unattended timer, use the bundled
lock-protected wrapper instead of raw lore sync so multiple source jobs do not
write ~/.lore/lore.db at the same time:
You don't need the MCP server to use Lore. The lore command opens the SQLite
store directly, so search, read-back, navigation, and writing all work
server-free anywhere you have a shell. The MCP server below is just one more
reader of the same store; nothing here depends on it.
The loop is always the same: drill down, never dump. A session can be millions of tokens, so you never page a whole one into context. Search broadly, take the real ids it hands back (you never invent one), then spend them:
Other commands round out the loop: lore status (freshness/health),
lore sessions (recent conversations), lore timeline (activity by day/hour),
and lore push (add a live session from a JSON batch on stdin). Add --json to
any of them for a machine-readable envelope.
Every search filter the MCP tools accept works here too (--project, --source,
--session, --branch, --agent, --skill, --tool, --role, --model,
--since, --until, --limit).
Before asking for a current brief or handoff, check freshness:
schemaVersion and supportedSchemaVersion tell you whether this build can
write to the store. Read-only search may still work against a newer compatible
store, but sync/index/push only run when the installed build supports the store
schema. In a source checkout, run npm run build before trusting the global
lore shim. For npm installs, run
npm install -g @jordanhindo/lore@latest and check lore status --json again.
CLI ⇄ MCP parity is proven, not asserted. Each lore … --json envelope is
byte-for-byte identical to the matching MCP tool's response, verified by a parity
test suite that runs both paths against one shared fixture store. So the CLI is a
faithful stand-in for the server:
| task | CLI | MCP tool | --json envelope |
|---|---|---|---|
| keyword search | lore search | search_memory | { count, hits } |
| recency-blended search | lore search --relevant | find_relevant | { count, hits } |
| one message | lore get | get_message | detail obj / { error, message_id } |
| neighbors | lore context | get_context | { messages } |
| session page | lore session | get_session | { messages, nextCursor } |
| session list | lore sessions | list_sessions | { count, sessions } |
| activity | lore timeline | timeline | { buckets } |
| status/freshness | lore status | status | status envelope |
| write | lore push | push | result / { error, detail } |
The bundled lore skill (skills/lore/) teaches an agent to drive this whole
loop: when to search, which id to spend, and how to drill down instead of
dumping. It's self-bootstrapping: its references/setup/index.md covers getting history
indexed in the first place (install, index/backfill a harness, write an adapter,
or push), so one npx skills add jordanhindo/lore installs the whole thing.
The low-level skills/lore/ skill teaches agents how to install Lore, index
transcripts, search memory, drill into message ids, and use the MCP server when
a harness supports it. The workflow pack sits above that substrate:
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.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.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.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.These are installable skill bundles, not one-file prompt snippets. Each workflow
skill includes SKILL.md, references, examples, eval specs, validator scripts
where structure is deterministic, and evals/test-report.md. A workflow skill is
not complete until its test report proves the eval/review pass ran and the bundle
validator passes.
There is no universal plugin wrapper in this release. A future plugin could
bundle names such as lore:recall, lore:brief, and lore:handoff, but today
the shipped surface is the package skills/ tree plus the lore CLI/MCP
substrate. Workflow skills may propose actions; they must not create jobs, edit
prompts, update wiki pages, create tasks, modify code, or run destructive memory
operations unless the user explicitly asks for that next step.
When you change any part of this pack, update the matching surface too: CLI help,
README, AGENT-ONBOARD.md, skills/lore, workflow skill docs, validators,
examples, eval reports, and package smoke checks should move together.
Packaging proof lives in:
That smoke builds the CLI, preserves executable mode for dist/cli/lore.js,
validates package dry-run metadata, packs a real tarball, reads the workflow
skill folders from the packaged tree, checks non-hollow test-report headings, and
verifies the packaged CLI help can run with dependencies present.
lore serve starts the MCP server over stdio. Point any MCP client at it.
Claude Code (add to ~/.claude/settings.json):
Cursor / Cline and friends: add an stdio server entry with the same
command / args shape in the client's MCP config.
| Tool | What it does |
|---|---|
status | Store health/freshness, schema version, source/project scoped counts. |
search_memory | Keyword search across every transcript, ranked by bm25, with filters. |
find_relevant | Like search_memory, but blends relevance with recency. |
get_message | Fetch one message by id (full=true returns the un-elided text). |
get_context | The neighbor window around an anchor message. |
get_session | One logical session as a folded, paginated timeline. |
list_sessions | Session rollups (counts, first / last activity), filterable. |
timeline | Bucketed activity over time, by day or hour. |
push | Write one normalized live JSON batch, matching CLI lore push. |
Every search tool takes the same dimension filters: project, branch,
source, agent, skill, tool, role, model, since, until, limit.
Your agent calls search_memory with a query (plus any filters) and gets back a
count and a ranked list of hits. Each hit carries the matched text and full
provenance, so the agent knows where the memory came from and can pull the rest
with get_message:
Long messages come back elided with a marker telling the agent how to fetch the
full text via get_message(message_id, full=true), so one giant transcript can
never blow the context window.
Compaction is the moment memory matters most, so catch fresh session content
before it disappears from the active context. The exact hook differs by harness:
Claude Code can call lore hook from PreCompact / SessionEnd when a hook
payload is available, or lore sync claude-code for manual catch-up when only
the transcript tree needs freshening. Timers should call
scripts/lore-sync-once.sh claude-code so the shared store write is locked.
Codex should use its notify wrapper or scripts/lore-sync-once.sh codex from a
timer because it writes a session tree rather than a transcript_path hook
payload.
The skill setup references carry the exact recipes:
skills/lore/references/setup/claude-code-hooks.md,
skills/lore/references/setup/codex-hooks.md,
and
skills/lore/references/setup/other-harness-hooks.md.
Don't see your agent on the list? lore sample <transcript-dir> summarizes its
on-disk format. It recognizes JSONL, SQLite databases (read via the file header,
never by loading the DB), and whole-file JSON, so you can see an unknown
harness's shape before writing anything. The bundled lore skill's
references/setup/index.md (skills/lore/references/setup/index.md) walks an agent from
"installed" to "my sessions are searchable," including writing and proving a new
adapter, or using the live push path when a harness keeps no files at all.
push is data only: it validates every record at the boundary and never
receives or executes code.
~/.lore/lore.db), lives outside any repo, and *.db
is gitignored. Move it with LORE_DB.--no-redact on lore index / lore hook / lore setup
if you really want credentials stored verbatim too.lore forget deletes a session or a
project (point-in-time); lore exclude deletes a project and bars all future
captures from it. Both print an exact-scope preview and only act when you add
--confirm, and both write a tombstone so re-indexing can't resurrect the
data. See the lore skill for the full preview-then-confirm protocol.source
namespace (claude-code, codex, openclaw, cursor, hermes). Any MCP
client can read everyone's history.source_file_id is a physical transcript file (the unit of
ingestion and the resume watermark). A session_id is a logical session shared
across a primary file and its subagent files. Each message gets a synthetic
message_id = hash(source_file_id + uuid + seq) because raw uuids collide.| Var | Default | Meaning |
|---|---|---|
LORE_DB | ~/.lore/lore.db | Store location. |
LORE_LOG_LEVEL | info | debug / info / warn / error. |
License: MIT.