lore

# Lore AI memory backed by Notion. Lore gives your AI assistants a persistent, shared memory: it stores conversations, decisions, follow-up tasks, and durable relationships as Notion pages that any teammate or agent session can read back. Anything you use with the [Model Context Protocol](https://modelcontextprotocol.io) (Claude Code, Codex, Cursor, OMP, and other MCP hosts) can recall, save, and reason over the same vault, so context survives `/clear`, new branches, and handoffs between people. Under the hood, Lore organizes a vault into five core Notion databases: Projects, Topics, Memories, Entities (canonical-handle resolution), and Facts. The same domain services power three surfaces: an MCP server for AI assistants, a CLI for humans, and hook commands that wire automatic context loading and session saving into supported hosts. ## Quick Start ### 1. Install Lore #### Install from npm (recommended) ```bash npm install -g @notionhq/lore # or npm install -D @notionhq/lore ``` Public npm requires no registry configuration or package token. #### Build from source ```bash git clone https://github.com/makenotion/lore.git cd lore && npm install && npm run build && npm link ``` `npm link` makes `lore` available globally on your `PATH` from the clone. Run `lore --version` to confirm either installation route, then continue with step 2 below. For project-local installs, run `npx lore <command>` from inside the project or add a `lore` script to `package.json`. See [`docs/dev-dependency-install.md`](docs/dev-dependency-install.md) for the Yarn PnP wiring and path-portable setup teams use to share assistant config across a repo. ### 2. Join an Existing Shared Vault Most operators should join an already initialized shared vault. A Lore vault is a Notion page that already contains the five databases (Projects, Topics, Memories, Entities, Facts). Joining that vault means pointing your local `.lore.yaml` at the shared `vault.pageId`; do not run database initialization against a shared page that your team lead has already bootstrapped. `.lore.yaml` is local-only. Keep it out of version control, and distribute shared values such as `vault.pageId` through onboarding docs instead of committing config. This is the current policy even for credential-free shared vault config and supersedes older changelog notes that allowed intentional committed config. Notion page IDs are access locators, not bearer credentials: knowing a page ID does not grant access unless the caller's Notion token can already read that page. Even so, keep `vault.pageId` out of version control so external clones of a public repo don't auto-target a maintainer's vault. If a personal or accidental page ID lands in git history, scrub the working tree and decide with the page owner whether to replace the page or rewrite history. #### Internal Notion engineer + shared vault Use Lore's ntn-backed auth flow. It auto-installs `ntn` when needed, runs `ntn login`, and stores the per-user token where Lore can read it. ```bash # Join by pointing local config at the initialized shared vault. # Do not run database initialization against an existing shared vault. cat > .lore.yaml <<'YAML' vault: pageId: "<shared-vault-page-id>" YAML lore auth --login lore auth --status lore status ``` #### External operator + shared vault Create a Notion Personal Access Token at `notion.so/developers/tokens`, then use it through the canonical Notion SDK environment variable. Do not use `secret_` integration tokens from `notion.so/profile/integrations` for team rollout; they share one rate-limit bucket across every operator using the same integration. Persist `NOTION_API_TOKEN` in your shell profile or assistant host environment before running `lore install` and restarting your assistant. ```bash export NOTION_API_TOKEN="<notion-pat>" # Join by pointing local config at the initialized shared vault. # Do not run database initialization against an existing shared vault. cat > .lore.yaml <<'YAML' vault: pageId: "<shared-vault-page-id>" YAML lore auth --status lore status ``` The last two commands verify that Lore can resolve auth and read the vault. After they pass, configure your assistant in step 3. Restart or reconnect the assistant after install or config changes so it reloads the MCP server and hooks. Token resolution order is `NOTION_API_TOKEN` -> ntn-resolved `auth.json`. The first source available wins. See [`docs/authentication.md`](docs/authentication.md) for the full priority chain, multi-workspace selection, and troubleshooting. If setup is broken and the next command is unclear, run `lore doctor` from the project. It performs read-only checks across config discovery, auth, vault access, MCP host config, hooks, and recent background hook failures, then ends with one prioritized next action. ### 3. Configure Your Assistant ```bash # Internal ntn path: lore install --ntn # External PAT path, after exporting NOTION_API_TOKEN: lore install ``` Both install paths configure every supported assistant integration (`--client all`, including OMP) and fill in any missing side from an older install. Use `--client` to install only one. Keep `--ntn` on client-scoped commands when using the internal ntn path; omit it for the PAT path after exporting `NOTION_API_TOKEN`: ```bash lore install --ntn --client claude lore install --ntn --client codex lore install --ntn --client cursor lore install --ntn --client omp lore install --ntn --client cursor --cursor-global ``` - `claude`: writes Claude Code settings plus `.mcp.json` - `codex`: writes `.codex/config.toml` plus `.codex/hooks.json` - `cursor`: writes `<projectDir>/.cursor/mcp.json` (`--cursor-global` opts into `~/.cursor/mcp.json`) - `omp`: writes the project `.omp/mcp.json` OMP's native `.omp/mcp.json` takes precedence over a root `.mcp.json` for OMP discovery. OMP receives Lore's MCP tools without Claude/Codex lifecycle hooks; restart OMP or run `/mcp reload` after installing or changing its config. Codex only loads project-scoped `.codex/*` files for trusted projects. Cursor's MCP runtime doesn't currently support session-end / Stop hooks, so the Cursor installer only writes the MCP entry; the Stop-triggered autosave and the detached auto-digest spawn run only under Claude Code or Codex. Recall / save / scan paths work identically across Claude Code, Codex, Cursor, and OMP. #### Other MCP Hosts For agents not directly supported by `lore install --client`, run `lore install --print-config json` or `lore install --print-config toml` and paste the emitted MCP server snippet into the host's config file. See [`docs/mcp-hosts.md`](docs/mcp-hosts.md) for host notes and hook limitations. OMP is already supported natively; do not use `--print-config` for OMP. Restart or reconnect your assistant after `lore install` or manual host config changes so it reloads the MCP server. For OMP, `/mcp reload` is also available; OMP does not install Lore lifecycle hooks. ### 4. Advanced and Maintenance Flows #### Team-lead / first-time shared-vault bootstrap Use this path only when you are creating the shared vault databases for the first time. Pick or create the Notion page your team will share, make sure your auth source can write to it, then run: ```bash lore init <page-id> ``` That command creates the five databases inside the page (Projects, Topics, Memories, Entities, Facts) and writes your local `.lore.yaml`. Operators who join the initialized vault later should use step 2 instead of running initialization again. See [`docs/team-rollout.md`](docs/team-rollout.md) for the per-engineer onboarding flow and team-lead runbook. #### Personal or Scratch Vault Creation For personal vaults or fresh-onboarding scratch use, the no-arg flow creates a workspace-level page on your behalf using the active auth source. If no auth resolves, it auto-installs ntn, runs `ntn login`, and then writes `.lore.yaml`: ```bash lore init # default title: "Lore Vault - <basename(cwd)>" lore init --name "Lore Vault Widget" # explicit title ``` For direct non-ntn setup, create a Notion Personal Access Token at `notion.so/developers/tokens`, set the canonical Notion SDK env var, and make sure the operator's Notion account can access the vault page before bootstrapping a new vault: ```bash export NOTION_API_TOKEN="<notion-pat>" ``` #### Dev-Environment Setup Use the dev environment only when you intentionally want a dev-environment vault: ```bash lore init --ntn-env dev ``` If your existing ntn auth points at a different environment than `--ntn-env`, Lore exits 1 with recovery copy (typically `ntn logout && NOTION_KEYRING=0 NOTION_ENV=<env> ntn login`) rather than silently creating a vault in the wrong environment. To run `ntn` yourself, set `NOTION_KEYRING=0` before logging in. `ntn` defaults to macOS Keychain storage, which Lore does not read; the env var forces file-mode storage at `~/.config/notion/auth.json`: ```bash NOTION_KEYRING=0 ntn login ``` Lore reads the resulting `auth.json` automatically. See [`docs/team-rollout.md#known-gotcha-direct-ntn-login-outside-lore`](docs/team-rollout.md#known-gotcha-direct-ntn-login-outside-lore) for the persistent shell-rc setup if you use `ntn` for other tooling too. #### Refresh Auth for an Existing Vault Once your local `.lore.yaml` points at a configured vault, refresh ntn auth and preflight access with: ```bash lore auth --login ``` Legacy token sources are not valid for new setup. `LORE_NOTION_TOKEN` is no longer read as an auth source; when no supported auth source resolves, Lore only mentions it as a migration hint. Any `auth.token` value in `.lore.yaml` is rejected at config load time. Use `NOTION_API_TOKEN` for Personal Access Tokens or `lore auth --login` for ntn auth. #### Legacy Four-Database Vault Migration Vaults created before the Entities database was introduced need one bootstrap step before the entity backfill: run `lore vault ensure-entities`, then run `lore migrate --build-entities --allow-unscoped` to preview the vault-wide backfill and `lore migrate --build-entities --allow-unscoped --yes` in a quiet window to canonicalize the fact graph. Use `--project <name>` in both commands for a project-scoped pass. ### 5. Teach Your Agents to Use Lore `lore install` wires the MCP server and hooks into the assistant host, but agents still need repo-local instructions that tell them to prefer the shared Lore vault for team knowledge. Add a "Memory and note-taking" section to the root `AGENTS.md` and, when the repo uses Claude Code, mirror it in `CLAUDE.md` or another host-specific instruction file. A minimal starter: ```markdown ### Memory and note-taking - Use Lore for cross-session and cross-team knowledge. Lore stores memories, facts, decisions, and tasks in the shared vault, so every team member and agent session benefits. Prefer Lore over file-based memory for anything the team should know. - Use file-based memory only for personal preferences or local-only context that should not be shared. - At session start, call `lore-context` with `action: "wake-up"` to load recent project context when the tool is available. - In Codex, automatic wake-up ranks against the first prompt. After `/clear` or a major topic pivot, call `lore-context` again with `action: "wake-up"` and `userQuery` set to the new task prompt. - Save non-obvious discoveries with `lore-memory` and `action: "save"`. - Record architectural decisions with `lore-decision` and `action: "create"`. - Record durable component relationships with `lore-fact` and `action: "create"` after saving a supporting memory; pass `sourceMemoryId`, or pass `agent` + `session` so Lore can auto-link the fact to the earlier memory in the same process. - Track follow-up work with `lore-task` and `action: "create"`; close tasks with `action: "close"` as soon as the work is done or cancelled. ``` Adapt the snippet to the repo. For example, if Lore is installed as a Yarn PnP devDependency, tell agents to run CLI commands as `yarn run -T lore <subcommand>` while still calling MCP tools by their normal `lore-*` names. ## Data Model A vault is a Notion page containing five core databases: | Database | Title Property | Key Properties | Relations | | ------------ | -------------- | ------------------------------------------------------ | ----------------------------------------------------- | | **Projects** | Name | Type (project/person/agent), Path, Status, Description | -- | | **Topics** | Name | Description | Project | | **Memories** | Title | Source, Author, Agent, Tags, Session + page body | Project, Topic | | **Entities** | Name | Aliases, Kind, Description | Project, Source (Memory) | | **Facts** | Subject | Predicate, Object, Valid From, Valid Until, Confidence | Project, Source (Memory), SubjectEntity, ObjectEntity | `lore init` creates all five databases on a new vault. Vaults created before the Entities database was introduced only have four (no Entities); they need a one-time legacy migration via `lore vault ensure-entities` to create the Entities database and add the `SubjectEntity` / `ObjectEntity` relation columns to Facts. Plan/apply the vault-wide backfill with `lore migrate --build-entities --allow-unscoped` and `lore migrate --build-entities --allow-unscoped --yes`, or use `--project <name>` in both commands for a project-scoped pass, to fill historical rows that do not already have relation values. See [`docs/team-rollout.md#entities-database-cutover`](docs/team-rollout.md#entities-database-cutover). **Predicate values accepted by `lore-fact action='create'`** are profile-aware. Generic predicates `is_a`, `has_a`, and `related_to` are always available; the active profile contributes the rest of the agent-writable predicate set. The default profile currently adds `uses`, `depends_on`, `created_by`, `owned_by`, `replaces`, `extends`, and `conflicts_with`, while other profiles can expose different domain-specific predicates. See [`docs/profiles.md#taxonomy-contract`](docs/profiles.md#taxonomy-contract) and the active profile taxonomy for the writable set in a given vault. System-managed predicates are `decided_by`, `supersedes_decision`, `informs` (`lore-decision action='create'` / `supersede`) and `mentions` (`lore-memory action='save'`). Historical tracking predicates (`needs_action`, `waiting_on`, `blocked_by`) are legacy row values only; use `lore-task action='create'` for tracked work. **Fact confidence (categorical)**: `certain`, `likely`, `speculative`. This is the agent-writable stance on Facts. The separate numeric Facts `Confidence Score` column is system-managed: read citations raise it, contradiction/supersession signals lower it, and neglect decay reduces untouched facts over time. Do not try to write the numeric score through MCP inputs. **Memory sources**: new writes accept `conversation`, `autosave_learning`, `file`, `manual`, and `digest`. `agent_diary` is retained for historical rows and explicit audit recall only. **Memory kinds**: `note`, `decision`, `incident`, `runbook`, `postmortem`, `policy`, `task`, `procedure`. Procedures are reviewed governance memory: propose them through `lore-procedure action='propose'`, then approve or reject them through `lore-memory action='approve'` / `lore-memory action='reject'`. `lore-memory action='save'` does not create `kind: "procedure"` rows. **Memory statuses**: `informational`, `proposed`, `accepted`, `superseded`, `deprecated`, `rejected` ### Topic keys Recurring non-procedure memory topics (`decision`, `runbook`, `incident`, `postmortem`, and `policy`) can pass `topicKey` to `lore-memory action='save'`. Rows upsert by `(Topic Key + exact Project relation set)`: a matching row gets a revision appended and its `Revision Count` incremented instead of creating a new memory. Use stable prefixes matching those save families: `decision/`, `runbook/`, `incident/`, `postmortem/`, and `policy/`. Procedure topic keys use the `procedure/` family, but they are supplied to `lore-procedure action='propose'` for proposal idempotency and conflict detection rather than to `lore-memory action='save'` for revision chains. Only the non-procedure save families form `lore-memory` revision chains; `note` and `task` kinds do not form revision chains. Use `lore-memory action='suggest-topic-key'` to derive a key, and see [`docs/memory-workflows.md`](docs/memory-workflows.md#topic-keys) for promotion and re-keying rules. Save digests regularly (`lore-context action='digest'` → synthesize → `lore-memory action='save'` with `source: "digest"`). When a digest from the last 7 days exists, `lore-context action='wake-up'` surfaces it at the top and trims the raw-memory list underneath — a denser, lower-token starting point than a long stream of individual memories. ## MCP Tools Lore exposes a small set of polymorphic tools, each multiplexing several actions behind one MCP registration. The prior single-purpose tool names and task aliases were removed in the 0.6.0 deprecation purge. See [`docs/mcp-tools.md`](docs/mcp-tools.md) for the current tool list, action reference, and task/fact migration notes. ## CLI Commands Core commands: - `lore init [page-id]` creates vault databases and writes `.lore.yaml`. - `lore install` writes assistant MCP config and supported hooks; add `--ntn` to select the internal ntn bootstrap path. - `lore auth --login` refreshes ntn auth and verifies vault access. - `lore doctor` diagnoses setup health and prints the next repair action. - `lore search <query>` searches memories. - `lore memory save <title>` saves a manual memory from the shell. - `lore decision create <statement>` records a decision with rationale. - `lore ask <entity>` queries facts and tasks about an entity. - `lore status` reports vault health and active project resolution. - `lore costs summary` summarizes the opt-in local cost ledger. - `lore migrate` runs schema and one-shot data migrations. - `lore entities merge --from <loser-id> --into <winner-id>` previews or applies duplicate Entity merges. - `lore conflicts scan` surfaces read-only conflict candidates for agent judgment. See [`docs/cli.md`](docs/cli.md) for a compact CLI command overview. See [`docs/conflict-detection.md`](docs/conflict-detection.md) for conflict verdict rules, scan caps, and the repeat-until-clean workflow. ## Hooks Lore installs hook commands for supported AI coding assistants: - **Auto-save** (`lore hooks autosave`) runs on assistant `Stop` and saves the session after enough user messages. - **Wake-up** (`lore hooks wakeup`) loads the latest digest, recent memories, active facts, and task-matched context before the first response. Claude Code and Codex installs wire hooks automatically using bin dispatch (`lore hooks ...`, or `yarn run -T lore hooks ...` under Yarn PnP). The `hooks/autosave.sh` and `hooks/wakeup.sh` scripts are compatibility entrypoints for older absolute-path installs. Cursor and `--print-config` hosts only get the MCP tool surface. See [`docs/hooks.md`](docs/hooks.md) for host timing, auth forwarding, auto-digest behavior, and compatibility notes. ## Configuration Lore is configured via `.lore.yaml`. The file is located by searching upward from the current working directory. `.lore.yaml` is local-only — keep it out of version control. Copy `.lore.example.yaml` to `.lore.yaml` and fill in your values, or run `lore init` to generate one. Distribute shared team values (`vault.pageId`, `auth.workspaceId`) through your onboarding docs rather than committing config; even credential-free shared vault config stays outside git under the current policy. Never put `auth.token`, personal scratch vault page IDs, or personally identifying values in the file. Threat-model posture for `vault.pageId`: a Notion page ID is not a credential, and exposing one does not bypass Notion permissions. Even so, keep page IDs out of git so external clones of a public repo don't auto-target an unrelated vault. A page ID that lands in history by accident should be removed from the working tree; history rewrite or page replacement is only needed when the owner considers the page location itself sensitive. ```yaml # Required: Notion page ID containing the vault databases vault: pageId: "<shared-team-vault-page-id>" # Optional: workspace selector for multi-workspace ntn auth.json setups # auth: # workspaceId: "workspace-id" # # Optional: read-only inherited vaults and deliberate promotion destinations. # Normal save/update tools still write only to vault.pageId. # upstreamVaults: # - name: "Engineering" # pageId: "engineering-vault-id" # priority: 10 # promotionTargets: # - name: "Team" # pageId: "team-vault-id" # requireReview: true # Map directories to named projects (for monorepo support) projects: - name: "Server" path: "src/server" tags: ["backend"] - name: "Client" path: "src/client" tags: ["frontend"] # Auto-detect projects from workspace patterns # detect: # patterns: ["packages/*/package.json"] # exclude: ["node_modules"] # Hook behavior hooks: autoSave: true # Inject digest, memories, tasks, active facts, and decisions at session start. # Set to false to skip the context injection (reduces prompt overhead # and the Notion round-trip at session start). wakeUp: true saveInterval: 5 # save after every 5 user messages ``` Token resolution order: `NOTION_API_TOKEN` environment variable, then ntn-resolved `~/.config/notion/auth.json`. The first available source wins. Any `auth.token` value in `.lore.yaml` is rejected at config load time; move credentials to `NOTION_API_TOKEN` or ntn auth. Multi-workspace ntn setups select a workspace with `NOTION_WORKSPACE_ID` or `auth.workspaceId`. Notion rate limits are per token. ntn-issued tokens and PATs give each operator an independent bucket; distributing one shared `secret_` integration token through `NOTION_API_TOKEN` collapses everyone onto one bucket. See [`AGENTS.md`](AGENTS.md#authentication) for the operational rationale, and [`src/auth/AGENTS.md`](src/auth/AGENTS.md) for the priority chain implementation, ntn version policy, and keychain-mode workaround. ### Environment variables | Variable | Effect | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NOTION_API_TOKEN` | Canonical Notion bearer token env var for Personal Access Tokens. Takes precedence over ntn `auth.json` | | `NOTION_WORKSPACE_ID` | Selects a workspace from a multi-workspace ntn `auth.json` | | `LORE_AGENT_NAME` | Override the `Agent:` field on saved memories (e.g., `LORE_AGENT_NAME=Codex`) | | `LORE_USER_NAME` | Override the `Author:` field on saved memories with a human display name. When unset, Lore resolves the engineer identity from `users.me` on the active ntn-issued token. | | `LORE_AUTO_DIGEST=false` | Suppress the Stop-triggered auto-digest scheduler (CLI `lore digest` still works) | | `LORE_NO_HYPERLINKS=1` | Skip OSC 8 clickable hyperlinks in `lore search` and `lore status` output, even under TTY. Same fallback as the non-TTY path. `=0`, `=false`, and empty string are treated as not set | | `NO_COLOR=1` | Honored alongside `LORE_NO_HYPERLINKS` to skip OSC 8 emission | ## Monorepo Support Projects map directories to named scopes using the `projects` array in `.lore.yaml`. Lore resolves the current project from your working directory using longest-prefix matching. Given this config: ```yaml projects: - name: "Root" path: "." - name: "Server" path: "src/server" - name: "Auth" path: "src/server/auth" ``` Running from `src/server/auth/middleware` resolves to the "Auth" project. Memories, facts, and searches are automatically scoped to the matched project. ## Development **Prerequisites**: Node.js 20+, npm ```bash npm install # Install dependencies npm run build # Build with tsup (ESM, 4 entry points) npm run typecheck # Type-check with tsc --noEmit npm run lint # Lint with eslint npm run lint:fix # Lint and auto-fix npm run format # Format with prettier npm run format:check # Check prettier formatting npm run test # Run tests with vitest npm run dev # Watch mode (tsup --watch) ``` See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`AGENTS.md`](AGENTS.md), and the subsystem guides under `src/*/AGENTS.md` for contributor conventions, architecture notes, and the non-negotiable stability rules. If you are changing anything under `.github/workflows/`, read [`docs/ci.md`](docs/ci.md) first — it documents the fork-safety contract every workflow must keep. ## Changelog Notable user-facing changes are recorded in [`CHANGELOG.md`](CHANGELOG.md). ## License MIT