Tags & scopes

Use the narrowest scope that correctly describes where the memory applies:

// Universal: always apply to every agent everywhere
scope: "global"

// Repo-level: applies to this codebase
scope: "repo::mthines/my-app"

// Branch-level: experimental, won't pollute the repo set
scope: "branch::mthines/my-app::feat/new-auth"

// Project-level: shared across a monorepo
scope: "project::my-monorepo"

Tags are arbitrary strings. Use a namespace::value convention to keep them readable:

memory.write {
  scope:  "global",
  key:    "aw-lessons::worktree-naming",
  value:  "Always use the branch name as the worktree directory name.",
  tags:   ["skill::aw", "source::stuck-loop", "loop::aw-lessons"],
  source_agent: "aw-executor",
  trigger: "stuck-loop"
}

Common tag namespaces used in the ecosystem:

• skill::aw / skill::fix-bug — which skill owns the memory (see the autonomous-workflow skill in mthines/agent-skills)
• loop::aw-lessons — part of the AW self-improvement loop
• source::stuck-loop / source::pr-webhook — what triggered the write

Pass tags to memory.list to narrow results:

memory.list {
  scope: "global",
  tags:  ["loop::aw-lessons"],
  limit: 50
}

memory.search supports owner-level wildcards in the scopes parameter:

memory.search {
  q:      "worktree naming conflict",
  scopes: ["repo::mthines/*", "global"],
  tags:   ["skill::aw"],
  limit:  10
}

Wildcards only work in memory.search — not in memory.read, memory.list, or memory.delete.

Agents should read from specific scopes first, then merge with broader ones. More-specific scopes win when the same key exists at multiple levels:

// Read order for a task on branch feat/x in mthines/gw-tools
memory.list { scope: "branch::mthines/gw-tools::feat/x" }
memory.list { scope: "repo::mthines/gw-tools" }
memory.list { scope: "project::gw-tools" }    // monorepo only
memory.list { scope: "global" }

The CLI offers several commands that respect the same scope/tag logic. You can also browse memories visually in the Explorer.

# Human-readable view of all applicable memories
npx @lorekit/cli list

# Full-text search
npx @lorekit/cli search "worktree"

# Inspect one memory in full
npx @lorekit/cli show --scope global --key aw-lessons::worktree-naming

# Scope precedence tree (which memory wins per key)
npx @lorekit/cli tree

# Flag low-quality or malformed memories
npx @lorekit/cli lint

# Find near-duplicates (Jaccard similarity)
npx @lorekit/cli dedupe