Configuration

Put team-wide policy — the connection URL, default tags, per-scope write rules — in a .lorekit.json at the repo root. It carries no secrets, so it is safe to commit:

// .lorekit.json — repo root, safe to commit (no secrets)
{
  "mode": "local",
  "store": ".lorekit",
  "mcp.endpoint": "https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp",
  "tags.default": ["team", "project::my-app"],
  "scope.defaults": {
    "repo::owner/name":     { "tags": ["team"] },
    "branch::owner/name::": { "tags": ["ephemeral"] }
  },
  "hooks.disabled": ["Stop"],
  "hooks.instructions": {
    "SessionStart":       "Focus on migration safety. Any lesson tagged 'migration' is high-priority.",
    "PostToolUseFailure": "When recording a failure, include the exact command and exit code.",
    "Stop":               null
  },
  "telemetry.disabled": true,
  "dedupe.threshold": 0.8
}

Machine-local preferences live in ~/.lorekit/config.json. This is where a privacy or compliance deny ceiling belongs — it can never be lifted by any repo default or env flag:

// ~/.lorekit/config.json — user/machine, not committed
{
  "deny": ["remote"],
  "tags.default": ["mads"],
  "hooks.adapter": "claude"
}

Use hooks.instructions to inject custom guidance into the four hook events. The agent sees your text appended to each event's output — your default LoreKit messages stay unchanged:

// .lorekit.json
{
  "hooks.instructions": {
    // Injected at session start, after the memory index.
    "SessionStart":       "Focus on migration safety. Any lesson tagged 'migration' is high-priority.",
    // Injected with the per-turn relevance block — only on a turn that already
    // has one, so it never adds a line to every prompt.
    "UserPromptSubmit":   "Prefer a memory that names the file you are editing.",
    // Injected alongside the failure nudge when a tool call fails.
    "PostToolUseFailure": "When recording a failure, include the exact command and exit code.",
    // Injected with the retrospective nudge at end-of-turn (null = disabled for this event).
    "Stop":               null
  }
}

Both config layers are merged — repo instructions come first, user instructions follow. Run lorekit doctor to see what's resolved for each event.

At session start LoreKit injects a compact index of the memories that apply to your working directory. How much of the agent's context that block may occupy is a character budget, not a memory count — a count says nothing about cost, and the same number is both padding for a small store and truncation for a large one.

A second bound holds it from the other direction: maxLessons, the number of lines the block may hold, default 100. The budget alone cannot stop a store of 500 one-word keys from rendering 400 lines inside it, and a 400-line index is unreadable however few characters it costs. Whichever of the two binds first decides the block — and at the default budget that is almost always maxChars, which is why maxLessons is better understood as the depth of the read than as the size of the block. See the note below.

// .lorekit.json
{
  "hooks.userPrompt": "on",
  "hooks.sessionStart": "hybrid",
  "hooks.sessionStart.maxChars": 3000,
  "hooks.sessionStart.maxLessons": 100,
  "hooks.sessionStart.loopCap": 1,
  "hooks.sessionStart.branchHint": "on"
}

Memories are ranked before the budget is spent, so the ones that survive are the most-recurring and most-recent, not merely the newest. They are also diversified — when several highly-ranked memories read almost the same (one task's iteration log, say), the near-duplicates are pushed down so the budget shows variety instead of the same lesson three times. And no single self-improvement loop can flood the block: a memory tagged loop::<bucket> (a host's own working memory, read back by that host through its tag filter) contributes at most one line to a general session, so one prolific bot's bookkeeping never crowds out your codebase's actual lessons. The ranking also takes a gentle hint from your current git branch: on a branch like feat/embedding-pipeline, memories about embeddings are nudged up (the leading type/ or author segment — feat, fix, a username, a bot name — is ignored, and a trunk branch like main adds no hint). It's a light touch: the branch only ever lifts an on-topic memory, never buries one, so your most-recurring and most-recent memories keep their place. When the budget runs out, the shape decides what happens to the rest:

• hybrid (default) — fill the budget, then add one line naming what was left out and where it lives:

  LoreKit: 9 of 50 memories loaded · repo::acme/widget — considerations, not rules; read any in full with memory.read.
  - (repo::acme/widget) migration-order — Always add the column before the backfill…
  - (global) flaky-e2e — The retry wrapper hides a real race in the fixture…
  More lore: repo::acme/widget 25+ · global 25+ — memory.search or memory.read to drill in.

• index — the same list with no trailing map. Truncation is silent, so prefer this only when you know the store is small.

• map — lead with the scope map and just three of the most salient memories. For a large store, where knowing the inventory matters more than any one memory.

The header reads 9 of 50 whenever the block is truncated, so an agent can tell that reaching for memory.search is worth it. The denominator is what the fetch returned, not what the store holds: each scope is read to a cap of maxLessons memories (100 by default), so a four-scope workspace tops out at 400. A count in the map ending in + (100+) is a scope that hit that cap — a lower bound, not a total. memory.search and memory.read reach past it.

The line ceiling sets the depth of the read, and that is where relevance comes from. maxLessons decides how many candidate memories are fetched per scope before any ranking happens. At the default of 100 the ranker chooses the ~25 lines it renders from up to 400 candidates across a four-scope hierarchy; at 25 it would be choosing from 100. On a store of any real size that is the difference between ranking the newest few percent and ranking a corpus — a memory you re-learned five times last quarter cannot win a slot it was never fetched for.

The read stops at 100 per scope, the largest page GET /memories will return, so a ceiling above 100 still reads 100 from each scope and fills its remaining lines from the others. Below 25 the read does not shrink: the ranker keeps a full pool and you simply see fewer lines.

That read happens on every session start, against files on disk in local mode or over the network in remote mode, and the diversity pass that de-duplicates the results scales with the ceiling too. Neither is free: the de-duplication pass is O(n·k) in candidates × rendered lines, measured at roughly 25–105 ms for the 400-candidate pool this default creates (it depends on how long your memories are), against ~15 ms for the old 100-candidate one. That is once per session start, not per turn — but if you raise the ceiling to 200 on a large store, expect closer to 170 ms.

To actually see a wider index, raise the budget as well; the ceiling alone will not do it, because maxChars runs out first:

// .lorekit.json — a deliberately wide index, for a large store
{
  "hooks.sessionStart.maxChars": 12000,
  "hooks.sessionStart.maxLessons": 200
}

A selection (which mode to use) is resolved highest-precedence first:

env LOREKIT_MODE → user config "mode" → repo config "mode" → built-in default ("remote")

A constraint (deny) always wins, regardless of the selection. Denies are a union across every layer and only accumulate:

• A user with "deny": ["remote"] can never be flipped to remote by a repo default or env flag.
• A repo or CI job with "deny": ["local"] makes local unselectable there, even against LOREKIT_MODE=local.
• off is never deniable, so it is always the terminal fallback.

Run the CLI doctor to see the resolved mode, which source decided it, and any active deny constraints:

npx @lorekit/cli doctor