lorekeep 0.6.0__tar.gz → 0.7.0__tar.gz

lorekeep-0.7.0/.github/workflows/auto-merge-release-please.yml

@@ -0,0 +1,47 @@
+name: auto-merge-release-please
+
+# When release-please creates or updates a Release PR, this workflow:
+# 1. Runs `uv lock` to sync the lockfile with the bumped version in pyproject.toml
+# 2. Commits the updated uv.lock back to the PR branch (if changed)
+# 3. Enables auto-merge so the PR merges once CI passes
+#
+# This ensures uv.lock is always correct in the release commit — no stale lockfile.
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare-and-auto-merge:
+    if: startsWith(github.head_ref, 'release-please--')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Sync uv.lock
+        run: uv lock
+        continue-on-error: true
+
+      - name: Commit uv.lock if changed
+        continue-on-error: true
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add uv.lock
+          git diff --cached --quiet || git commit -m "chore: sync uv.lock"
+          git push || true
+
+      - name: Enable auto-merge for Release PR
+        run: |
+          sleep 3
+          gh pr merge --auto --squash "${{ github.event.pull_request.html_url }}"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

lorekeep-0.7.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.7.0"
+}

{lorekeep-0.6.0 → lorekeep-0.7.0}/AGENTS.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-Lorekeep compiles a team's raw markdown docs into a **temporal knowledge graph** (`facts.jsonl`) and exposes it to coding agents (Claude Code, Cursor, Codex, opencode) over MCP, with per-namespace permission. Agents read facts through 8 read tools and propose new facts through 5 journal-based write tools (confidence-gated, merged on resolve). Knowledge is processed once at compile time, not re-RAG'd per query.
+Lorekeep compiles a team's raw markdown docs into a **temporal knowledge graph** (`facts.jsonl`) and exposes it to coding agents (Claude Code, Cursor, Codex, opencode) over MCP, with per-namespace permission. Agents read facts through 9 read tools and propose new facts through 5 journal-based write tools (confidence-gated, merged on resolve). Knowledge is processed once at compile time, not re-RAG'd per query.
 
 ## Commands
 
@@ -29,7 +29,7 @@ uv run lorekeep <command>                    # run the CLI in dev mode
 | `check` | Validate compiled graph loads, no dangling edges (exit 1 on failure) |
 | `eval` | Tier-1 construction P/R/F1 vs gold corpus + structure metrics |
 | `wiki` | Regenerate `wiki/` from `facts.jsonl` (Obsidian-compatible markdown) |
-| `serve [--transport stdio\|http]` | Run the MCP server (8 read + 5 write tools) |
+| `serve [--transport stdio\|http]` | Run the MCP server (9 read + 5 write tools) |
 | `mcp add --agent claude\|cursor\|codex\|opencode --ns NS` | Write agent MCP config |
 | `import --from claude\|cursor\|codex\|opencode` | Import agent sessions into `raw/` |
 | `doctor` | Verify install: graph loads, schema valid, a tool responds |
@@ -58,7 +58,7 @@ Pydantic, all `frozen=True`, `extra="forbid"`. `Node` / `Edge` are the two `kind
 - **`perm/ns.py` `ScopedGraph`** — the **single permission chokepoint**. Wraps a `GraphStore` and filters *every* query. Deny-by-default: `effective_ns = allowed ∪ {public}`; a node is visible iff `ns ∩ effective_ns ≠ ∅`; an edge iff **both** endpoints visible **and** `edge.ns ∩ effective_ns ≠ ∅` (an edge never leaks a neighbor the caller can't see). **Any new query path must go through `ScopedGraph`, not `GraphStore` directly.**
 
 ### Serve (`mcp_server.py`)
-`FastMCP` with 8 read tools (`search`, `get_node`, `neighbors`, `at_time`, `history`, `changes`, `list_namespaces`, `schema`) and 5 write tools (`propose_fact`, `link_facts`, `flag_contradiction`, `update_fact`, `suggest_improvement`). Module-global `ScopedGraph` is set by `configure()`; `_require()` lazy-reloads when `facts.jsonl` mtime changes (so `compile` is visible without reconnecting). Tools are plain functions registered with `@mcp.tool()` but stay directly callable — **tests invoke them directly, no MCP transport**. The writer uses atomic `os.replace` so lazy-reload never reads a half-written file.
+`FastMCP` with 9 read tools (`search`, `get_node`, `neighbors`, `at_time`, `history`, `changes`, `list_namespaces`, `schema`, `meta`) and 5 write tools (`propose_fact`, `link_facts`, `flag_contradiction`, `update_fact`, `suggest_improvement`). Module-global `ScopedGraph` is set by `configure()`; `_require()` lazy-reloads when `facts.jsonl` mtime changes (so `compile` is visible without reconnecting). `_manifest` global loads `manifest.json` alongside facts (for `meta` tool's `compiled_at` + `merged_count`). Tools are plain functions registered with `@mcp.tool()` but stay directly callable — **tests invoke them directly, no MCP transport**. The writer uses atomic `os.replace` so lazy-reload never reads a half-written file.
 
 ### Wiki (`wiki.py`)
 Pure JSONL → markdown transform (no LLM). `generate_wiki(graph_dir, wiki_dir)` reads `facts.jsonl` via `GraphStore` → entity pages (`entities/<type>/<slug>.md` with YAML frontmatter, wikilinks, props table), `index.md` (catalog), `overview.md` (stats dashboard), `log.md` (append-only, preserved across regen). Builds into `.wiki-build.tmp` then `os.rename` swaps into place (atomic). `_slug()` replaces `:`/`/` with `-`; collisions raise `ValueError`. YAML scalars quoted via `json.dumps` so IDs like `svc:payments-api` parse correctly. Props table escapes `\|`, collapses newlines, serializes non-strings. Regenerates on every `facts.jsonl` mutation: `compile` (single regen — `_do_auto_resolve` returns bool, compile skips if resolve already regend), `resolve` (gated on merge/flag), daemon auto-resolve (on actual merge). Best-effort — never blocks compile or resolve.

{lorekeep-0.6.0 → lorekeep-0.7.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.0](https://github.com/manhhailua/lorekeep/compare/v0.6.1...v0.7.0) (2026-06-30)
+
+
+### Features
+
+* add scope-awareness meta tool — 9th MCP read tool ([#72](https://github.com/manhhailua/lorekeep/issues/72)) ([d7a6c95](https://github.com/manhhailua/lorekeep/commit/d7a6c950ea009bea8c22c81850336b7a3ae0eb12))
+
+## [0.6.1](https://github.com/manhhailua/lorekeep/compare/v0.6.0...v0.6.1) (2026-06-30)
+
+
+### Documentation
+
+* sync README with shipped features ([#70](https://github.com/manhhailua/lorekeep/issues/70)) ([ea81476](https://github.com/manhhailua/lorekeep/commit/ea81476f4ad49938a5bf1d616e6658ab8b204b36))
+
 ## [0.6.0](https://github.com/manhhailua/lorekeep/compare/v0.5.0...v0.6.0) (2026-06-29)
 
 

{lorekeep-0.6.0 → lorekeep-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lorekeep
-Version: 0.6.0
+Version: 0.7.0
 Summary: Temporal knowledge graph for AI agents via MCP
 Project-URL: Homepage, https://github.com/manhhailua/lorekeep
 Project-URL: Repository, https://github.com/manhhailua/lorekeep
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 Lorekeep compiles a team's raw documentation into a versioned, time-aware
 knowledge graph (`facts.jsonl`) and exposes it to coding agents (Claude Code,
-Cursor, Codex) through the Model Context Protocol — with per-namespace
+Cursor, Codex, opencode) through the Model Context Protocol — with per-namespace
 permission and zero servers to run.
 
 It applies Andrej Karpathy's "LLM Knowledge Base" idea: raw docs are the
@@ -69,13 +69,16 @@ knowledge.
 - **Namespace permission** — facts are tagged `ns` from the directory tree
   (`raw/<ns>/`); agents scoped to namespaces; cross-namespace edges
   hidden unless both endpoints are visible. Deny-by-default.
-- **MCP, stdio-first** — `lorekeep serve` exposes 8 read + 5 write tools;
+- **MCP, stdio-first** — `lorekeep serve` exposes 9 read + 5 write tools;
   `lorekeep mcp add` wires Claude Code / Cursor / Codex / opencode.
 - **Autonomous agent daemon** — `lorekeep agent watch` keeps the graph current:
   auto-compile on raw/ change, auto-resolve pending journals, delta import of
   agent session memory. Runs in the background; MCP server lazy-reloads.
-- **Lazy-reload** — graph updates (compile or resolve) are visible on the next
-  query. Connect once, use forever.
+- **Session-end hooks** — `lorekeep hook` auto-imports agent memory when a
+  session ends (Claude / Cursor / Codex / opencode). Wired by `mcp add`.
+- **Obsidian wiki** — auto-generated after every compile/resolve: human-browsable
+  markdown pages with `[[wikilinks]]`, YAML frontmatter, graph view.
+- **Lazy-reload** — graph updates visible on next query. Connect once, use forever.
 - **Provider-pluggable extraction** — litellm (OpenAI / Anthropic /
   DashScope/Qwen / Ollama). Strict-privacy → Ollama, fully local.
 - **Tier-1 eval** — extraction P/R/F1 vs a gold corpus, entity-resolution F1,
@@ -103,7 +106,7 @@ mkdir -p ~/.local/share/lorekeep/raw/backend
 cp your-docs.md ~/.local/share/lorekeep/raw/backend/
 
 # 3. set a provider (edit ~/.config/lorekeep/config.yaml), then compile
-uvx lorekeep compile                # raw/*.md -> graph/facts.jsonl
+uvx lorekeep compile                # raw/*.md → graph/facts.jsonl + wiki/
 
 # 4. wire a coding agent (writes a portable .mcp.json)
 uvx lorekeep mcp add --agent claude --ns backend
@@ -112,7 +115,7 @@ uvx lorekeep mcp add --agent claude --ns backend
 uvx lorekeep doctor
 ```
 
-Restart Claude Code → 13 Lorekeep tools are available (8 read + 5 write), scoped to your namespace.
+Restart Claude Code → 14 Lorekeep tools are available (9 read + 5 write), scoped to your namespace. Open `~/.local/share/lorekeep/wiki/` in Obsidian to browse the graph as a human.
 
 ## Lifecycle
 
@@ -124,23 +127,23 @@ The full journey from install to continuous use — see the
  ════          ═══════             ══════             ════════════          ════
  ┌─────┐   ┌──────────┐        ┌─────────┐       ┌───────────────┐    ┌────────┐
  │init │──►│raw/*.md  │──►     │mcp add  │──►    │ agent watch   │──► │backup  │
- │     │   │compile   │ compile│serve    │ serve │  raw/  → compile│   │        │
- │     │   │          │────────│         │       │  pending/ → resolve   │
- └─────┘   └──────────┘        └─────────┘       │  memory/ → import │    └────────┘
-                                   ▲             └───────┬───────┘         │
-                                   │                     │ lazy-reload     │ git sync
-                                   │◄────────────────────┘                 │
-                                   │◄──────────────────────────────────────┘
+ │     │   │compile   │ compile│serve    │ serve │  raw/    → compile   │
+ │     │   │          │────────│+hook    │       │  pending/ → resolve  │
+ └─────┘   └──────────┘   wiki │         │       │  memory/  → import   └────────┘
+                               └─────────┘       └───────┬───────┘         │
+                                    ▲                     │ lazy-reload     │ git sync
+                                    │◄────────────────────┘                 │
+                                    │◄──────────────────────────────────────┘
 ```
 
 | Step | Command | What it does |
 |---|---|---|
 | 1. Bootstrap | `lorekeep init` | Create data home (config + schema + dirs) |
 | 2. Curate | `raw/<ns>/*.md` | Drop markdown docs under namespace dirs |
-| 3. Compile | `lorekeep compile` | LLM-extract facts → `facts.jsonl` (cached, deterministic) |
-| 4. Wire agent | `lorekeep mcp add --agent claude --ns <ns>` | Write `.mcp.json`, scoped to namespace |
+| 3. Compile | `lorekeep compile` | LLM-extract → `facts.jsonl` + `wiki/` (cached, deterministic) |
+| 4. Wire agent | `lorekeep mcp add --agent claude --ns <ns>` | Write `.mcp.json` + session-end hook, scoped to namespace |
 | 5. Verify | `lorekeep doctor` | Graph loads, schema valid, tool responds |
-| 6. Serve | `lorekeep serve` | MCP server (8 read + 5 write tools, lazy-reload) |
+| 6. Serve | `lorekeep serve` | MCP server (9 read + 5 write tools, lazy-reload) |
 | 7. Keep current | `lorekeep agent watch &` | Daemon: auto-compile, auto-resolve, delta-import sessions |
 | 8. Back up | `lorekeep backup` | Push data home to private git repo (raw/ + schema.json) |
 
@@ -156,13 +159,13 @@ raw/<ns>/*.md ──► ingest ──► extract(LLM) ──┐
                                             │
 agent propose ──► MCP write tools ──► ──────┤
   (ZERO LLM cost, journal append)           │
-                                            ├──► resolve ──► writer ──► facts.jsonl
-import ──► raw/ ──► compile ────────────────┘    (pure logic,          │
-                                                   ZERO LLM)            │
+                                            ├──► resolve ──► writer ──► facts.jsonl ──► wiki/*.md
+import ──► raw/ ──► compile ────────────────┘    (pure logic,    (sorted)       (Obsidian)
+                                                   ZERO LLM)
                                                         ┌───────────────┘
                                                         ▼ (git / S3 sync)
                SERVE + QUERY (runtime, per device)
-facts.jsonl ──load──► GraphStore ──► ScopedGraph(ns) ──► MCP ──► agent
+facts.jsonl ──load──► GraphStore ──► ScopedGraph(ns) ──► MCP (9 read + 5 write) ──► agent
                          ▲              ▲                      │
                           │              │         ◄── read queries
                           │              └────────── write proposals (journal)
@@ -172,14 +175,14 @@ facts.jsonl ──load──► GraphStore ──► ScopedGraph(ns) ──► M
                lorekeep agent watch:
                  ├── watch raw/ → auto-compile
                  ├── watch pending/ → auto-resolve
-                 └── watch Claude memory/ → delta import → raw/
+                 └── watch agent memory/ → delta import → raw/
 ```
 
 **Three write paths → one resolve**: markdown is compiled by an LLM (chunked + cached); agents propose facts at runtime through MCP write tools at **zero marginal LLM cost** (the agent already ran the LLM for the conversation); agent sessions are imported into raw/. All converge at `resolve` — pure Python logic that merges, deduplicates, validates, and writes byte-stable `facts.jsonl`.
 
 **Serve**: `GraphStore` loads `facts.jsonl` into a networkx graph with temporal
 queries. `ScopedGraph` is the single permission chokepoint — every query is
-filtered through strict visibility rules. The FastMCP server exposes 8 read
+filtered through strict visibility rules. The FastMCP server exposes 9 read
 + 5 write tools over `ScopedGraph`. It lazy-reloads when
 `facts.jsonl` changes, so `compile` is instantly visible without reconnecting.
 
@@ -205,11 +208,11 @@ that began/ended in the window).
 
 **Agent-driven knowledge** — agents propose facts at runtime through MCP write tools (zero LLM cost). Facts land in `pending/<ns>/journal.jsonl` with agent id, confidence score, and timestamp. Resolve merges them into the graph: high-confidence (≥0.8) auto-merge, medium (0.5-0.8) merge + flag, low (<0.5) quarantine.
 
-**Autonomous agent daemon** — `lorekeep agent watch` keeps the graph current: watches `raw/` for changes → auto-compile; monitors `pending/` → auto-resolve; delta-imports Claude session memory into `raw/`. Scheduled lint and weekly suggestions are planned. See [docs/architecture/agent.md](docs/architecture/agent.md).
+**Autonomous agent daemon** — `lorekeep agent watch` keeps the graph current: watches `raw/` for changes → auto-compile; monitors `pending/` → auto-resolve; delta-imports agent session memory (Claude / Cursor / Codex / opencode) into `raw/`. Session-end hooks auto-trigger `lorekeep hook` when the agent exits. Scheduled lint and weekly suggestions are planned. See [docs/architecture/agent.md](docs/architecture/agent.md).
 
-## MCP tools (8 read + 5 write, scoped)
+## MCP tools (9 read + 5 write, scoped)
 
-**Read:** `search` · `get_node` · `neighbors` · `at_time` · `history` · `changes` · `list_namespaces` · `schema`.
+**Read:** `search` · `get_node` · `neighbors` · `at_time` · `history` · `changes` · `list_namespaces` · `schema` · `meta`.
 
 **Write** (journal-based, zero LLM cost): `propose_fact` · `link_facts` · `flag_contradiction` · `update_fact` · `suggest_improvement`.
 
@@ -263,23 +266,24 @@ src/lorekeep/
   defaults.py          default schema + config (for `init`)
   config.py, schema_io.py
   compile/{ingest,extract,resolve,writer}.py    the compile pipeline
-  compile/providers.py                          LLMProvider (Fake/LiteLLM)
+  compile/providers.py                          LiteLLMProvider (OpenAI/Anthropic/Ollama)
   journal.py           append-only journal writer + loader
   agent.py             autonomous agent: ingest, lint, suggest, status, watch
   store/{graph,fts}.py                          GraphStore + optional FTS cache
   perm/ns.py                                    ScopedGraph permission chokepoint
-  mcp_server.py                                 FastMCP + 8 read + 5 write tools
+  mcp_server.py                                 FastMCP + 9 read + 5 write tools
   wiki.py                                        Obsidian-compatible wiki generator
+  importer/{claude,cursor,codex,opencode}.py    agent session → raw/ importers
   integrations/{claude_code,cursor,codex,opencode,common}.py
   pipeline.py, cli.py
   eval/{gold,construction,retrieval}.py
-tests/                 ~140 tests
+tests/                 ~310 tests
 docs/                  README.md index, architecture/, guides/
 ```
 
 ## Status
 
-**v1 (implemented)** — compile pipeline + serve (store/permission/MCP read+write/4-agent integrations) + import (Claude/Cursor/Codex/opencode) + session-end hooks + agent daemon (watch/ingest/lint/suggest/status) + journal + resolve + data-home + dev mode + lazy-reload + backup + eval + **wiki** (Obsidian-compatible markdown output). Published to PyPI as `lorekeep`.
+**v1 (implemented)** — compile pipeline + serve (store/permission/MCP 9 read+5 write/4-agent integrations) + import (Claude/Cursor/Codex/opencode) + session-end hooks + agent daemon (watch/ingest/lint/suggest/status) + journal + resolve + data-home + dev mode + lazy-reload + backup + eval + scope awareness (`meta` tool) + **wiki** (Obsidian-compatible markdown output). Published to PyPI as `lorekeep`.
 
 **Phase 2 (planned)** — streamable-HTTP team server, OIDC/SSO, embeddings/hybrid search, scheduled nightly lint/suggest in daemon, schema evolve, full Tier-2 benchmark datasets (HotpotQA/CronQuestions) and the bespoke Tier-3 Lorekeep-Reason eval.
 

{lorekeep-0.6.0 → lorekeep-0.7.0}/README.md

@@ -8,7 +8,7 @@
 
 Lorekeep compiles a team's raw documentation into a versioned, time-aware
 knowledge graph (`facts.jsonl`) and exposes it to coding agents (Claude Code,
-Cursor, Codex) through the Model Context Protocol — with per-namespace
+Cursor, Codex, opencode) through the Model Context Protocol — with per-namespace
 permission and zero servers to run.
 
 It applies Andrej Karpathy's "LLM Knowledge Base" idea: raw docs are the
@@ -47,13 +47,16 @@ knowledge.
 - **Namespace permission** — facts are tagged `ns` from the directory tree
   (`raw/<ns>/`); agents scoped to namespaces; cross-namespace edges
   hidden unless both endpoints are visible. Deny-by-default.
-- **MCP, stdio-first** — `lorekeep serve` exposes 8 read + 5 write tools;
+- **MCP, stdio-first** — `lorekeep serve` exposes 9 read + 5 write tools;
   `lorekeep mcp add` wires Claude Code / Cursor / Codex / opencode.
 - **Autonomous agent daemon** — `lorekeep agent watch` keeps the graph current:
   auto-compile on raw/ change, auto-resolve pending journals, delta import of
   agent session memory. Runs in the background; MCP server lazy-reloads.
-- **Lazy-reload** — graph updates (compile or resolve) are visible on the next
-  query. Connect once, use forever.
+- **Session-end hooks** — `lorekeep hook` auto-imports agent memory when a
+  session ends (Claude / Cursor / Codex / opencode). Wired by `mcp add`.
+- **Obsidian wiki** — auto-generated after every compile/resolve: human-browsable
+  markdown pages with `[[wikilinks]]`, YAML frontmatter, graph view.
+- **Lazy-reload** — graph updates visible on next query. Connect once, use forever.
 - **Provider-pluggable extraction** — litellm (OpenAI / Anthropic /
   DashScope/Qwen / Ollama). Strict-privacy → Ollama, fully local.
 - **Tier-1 eval** — extraction P/R/F1 vs a gold corpus, entity-resolution F1,
@@ -81,7 +84,7 @@ mkdir -p ~/.local/share/lorekeep/raw/backend
 cp your-docs.md ~/.local/share/lorekeep/raw/backend/
 
 # 3. set a provider (edit ~/.config/lorekeep/config.yaml), then compile
-uvx lorekeep compile                # raw/*.md -> graph/facts.jsonl
+uvx lorekeep compile                # raw/*.md → graph/facts.jsonl + wiki/
 
 # 4. wire a coding agent (writes a portable .mcp.json)
 uvx lorekeep mcp add --agent claude --ns backend
@@ -90,7 +93,7 @@ uvx lorekeep mcp add --agent claude --ns backend
 uvx lorekeep doctor
 ```
 
-Restart Claude Code → 13 Lorekeep tools are available (8 read + 5 write), scoped to your namespace.
+Restart Claude Code → 14 Lorekeep tools are available (9 read + 5 write), scoped to your namespace. Open `~/.local/share/lorekeep/wiki/` in Obsidian to browse the graph as a human.
 
 ## Lifecycle
 
@@ -102,23 +105,23 @@ The full journey from install to continuous use — see the
  ════          ═══════             ══════             ════════════          ════
  ┌─────┐   ┌──────────┐        ┌─────────┐       ┌───────────────┐    ┌────────┐
  │init │──►│raw/*.md  │──►     │mcp add  │──►    │ agent watch   │──► │backup  │
- │     │   │compile   │ compile│serve    │ serve │  raw/  → compile│   │        │
- │     │   │          │────────│         │       │  pending/ → resolve   │
- └─────┘   └──────────┘        └─────────┘       │  memory/ → import │    └────────┘
-                                   ▲             └───────┬───────┘         │
-                                   │                     │ lazy-reload     │ git sync
-                                   │◄────────────────────┘                 │
-                                   │◄──────────────────────────────────────┘
+ │     │   │compile   │ compile│serve    │ serve │  raw/    → compile   │
+ │     │   │          │────────│+hook    │       │  pending/ → resolve  │
+ └─────┘   └──────────┘   wiki │         │       │  memory/  → import   └────────┘
+                               └─────────┘       └───────┬───────┘         │
+                                    ▲                     │ lazy-reload     │ git sync
+                                    │◄────────────────────┘                 │
+                                    │◄──────────────────────────────────────┘
 ```
 
 | Step | Command | What it does |
 |---|---|---|
 | 1. Bootstrap | `lorekeep init` | Create data home (config + schema + dirs) |
 | 2. Curate | `raw/<ns>/*.md` | Drop markdown docs under namespace dirs |
-| 3. Compile | `lorekeep compile` | LLM-extract facts → `facts.jsonl` (cached, deterministic) |
-| 4. Wire agent | `lorekeep mcp add --agent claude --ns <ns>` | Write `.mcp.json`, scoped to namespace |
+| 3. Compile | `lorekeep compile` | LLM-extract → `facts.jsonl` + `wiki/` (cached, deterministic) |
+| 4. Wire agent | `lorekeep mcp add --agent claude --ns <ns>` | Write `.mcp.json` + session-end hook, scoped to namespace |
 | 5. Verify | `lorekeep doctor` | Graph loads, schema valid, tool responds |
-| 6. Serve | `lorekeep serve` | MCP server (8 read + 5 write tools, lazy-reload) |
+| 6. Serve | `lorekeep serve` | MCP server (9 read + 5 write tools, lazy-reload) |
 | 7. Keep current | `lorekeep agent watch &` | Daemon: auto-compile, auto-resolve, delta-import sessions |
 | 8. Back up | `lorekeep backup` | Push data home to private git repo (raw/ + schema.json) |
 
@@ -134,13 +137,13 @@ raw/<ns>/*.md ──► ingest ──► extract(LLM) ──┐
                                             │
 agent propose ──► MCP write tools ──► ──────┤
   (ZERO LLM cost, journal append)           │
-                                            ├──► resolve ──► writer ──► facts.jsonl
-import ──► raw/ ──► compile ────────────────┘    (pure logic,          │
-                                                   ZERO LLM)            │
+                                            ├──► resolve ──► writer ──► facts.jsonl ──► wiki/*.md
+import ──► raw/ ──► compile ────────────────┘    (pure logic,    (sorted)       (Obsidian)
+                                                   ZERO LLM)
                                                         ┌───────────────┘
                                                         ▼ (git / S3 sync)
                SERVE + QUERY (runtime, per device)
-facts.jsonl ──load──► GraphStore ──► ScopedGraph(ns) ──► MCP ──► agent
+facts.jsonl ──load──► GraphStore ──► ScopedGraph(ns) ──► MCP (9 read + 5 write) ──► agent
                          ▲              ▲                      │
                           │              │         ◄── read queries
                           │              └────────── write proposals (journal)
@@ -150,14 +153,14 @@ facts.jsonl ──load──► GraphStore ──► ScopedGraph(ns) ──► M
                lorekeep agent watch:
                  ├── watch raw/ → auto-compile
                  ├── watch pending/ → auto-resolve
-                 └── watch Claude memory/ → delta import → raw/
+                 └── watch agent memory/ → delta import → raw/
 ```
 
 **Three write paths → one resolve**: markdown is compiled by an LLM (chunked + cached); agents propose facts at runtime through MCP write tools at **zero marginal LLM cost** (the agent already ran the LLM for the conversation); agent sessions are imported into raw/. All converge at `resolve` — pure Python logic that merges, deduplicates, validates, and writes byte-stable `facts.jsonl`.
 
 **Serve**: `GraphStore` loads `facts.jsonl` into a networkx graph with temporal
 queries. `ScopedGraph` is the single permission chokepoint — every query is
-filtered through strict visibility rules. The FastMCP server exposes 8 read
+filtered through strict visibility rules. The FastMCP server exposes 9 read
 + 5 write tools over `ScopedGraph`. It lazy-reloads when
 `facts.jsonl` changes, so `compile` is instantly visible without reconnecting.
 
@@ -183,11 +186,11 @@ that began/ended in the window).
 
 **Agent-driven knowledge** — agents propose facts at runtime through MCP write tools (zero LLM cost). Facts land in `pending/<ns>/journal.jsonl` with agent id, confidence score, and timestamp. Resolve merges them into the graph: high-confidence (≥0.8) auto-merge, medium (0.5-0.8) merge + flag, low (<0.5) quarantine.
 
-**Autonomous agent daemon** — `lorekeep agent watch` keeps the graph current: watches `raw/` for changes → auto-compile; monitors `pending/` → auto-resolve; delta-imports Claude session memory into `raw/`. Scheduled lint and weekly suggestions are planned. See [docs/architecture/agent.md](docs/architecture/agent.md).
+**Autonomous agent daemon** — `lorekeep agent watch` keeps the graph current: watches `raw/` for changes → auto-compile; monitors `pending/` → auto-resolve; delta-imports agent session memory (Claude / Cursor / Codex / opencode) into `raw/`. Session-end hooks auto-trigger `lorekeep hook` when the agent exits. Scheduled lint and weekly suggestions are planned. See [docs/architecture/agent.md](docs/architecture/agent.md).
 
-## MCP tools (8 read + 5 write, scoped)
+## MCP tools (9 read + 5 write, scoped)
 
-**Read:** `search` · `get_node` · `neighbors` · `at_time` · `history` · `changes` · `list_namespaces` · `schema`.
+**Read:** `search` · `get_node` · `neighbors` · `at_time` · `history` · `changes` · `list_namespaces` · `schema` · `meta`.
 
 **Write** (journal-based, zero LLM cost): `propose_fact` · `link_facts` · `flag_contradiction` · `update_fact` · `suggest_improvement`.
 
@@ -241,23 +244,24 @@ src/lorekeep/
   defaults.py          default schema + config (for `init`)
   config.py, schema_io.py
   compile/{ingest,extract,resolve,writer}.py    the compile pipeline
-  compile/providers.py                          LLMProvider (Fake/LiteLLM)
+  compile/providers.py                          LiteLLMProvider (OpenAI/Anthropic/Ollama)
   journal.py           append-only journal writer + loader
   agent.py             autonomous agent: ingest, lint, suggest, status, watch
   store/{graph,fts}.py                          GraphStore + optional FTS cache
   perm/ns.py                                    ScopedGraph permission chokepoint
-  mcp_server.py                                 FastMCP + 8 read + 5 write tools
+  mcp_server.py                                 FastMCP + 9 read + 5 write tools
   wiki.py                                        Obsidian-compatible wiki generator
+  importer/{claude,cursor,codex,opencode}.py    agent session → raw/ importers
   integrations/{claude_code,cursor,codex,opencode,common}.py
   pipeline.py, cli.py
   eval/{gold,construction,retrieval}.py
-tests/                 ~140 tests
+tests/                 ~310 tests
 docs/                  README.md index, architecture/, guides/
 ```
 
 ## Status
 
-**v1 (implemented)** — compile pipeline + serve (store/permission/MCP read+write/4-agent integrations) + import (Claude/Cursor/Codex/opencode) + session-end hooks + agent daemon (watch/ingest/lint/suggest/status) + journal + resolve + data-home + dev mode + lazy-reload + backup + eval + **wiki** (Obsidian-compatible markdown output). Published to PyPI as `lorekeep`.
+**v1 (implemented)** — compile pipeline + serve (store/permission/MCP 9 read+5 write/4-agent integrations) + import (Claude/Cursor/Codex/opencode) + session-end hooks + agent daemon (watch/ingest/lint/suggest/status) + journal + resolve + data-home + dev mode + lazy-reload + backup + eval + scope awareness (`meta` tool) + **wiki** (Obsidian-compatible markdown output). Published to PyPI as `lorekeep`.
 
 **Phase 2 (planned)** — streamable-HTTP team server, OIDC/SSO, embeddings/hybrid search, scheduled nightly lint/suggest in daemon, schema evolve, full Tier-2 benchmark datasets (HotpotQA/CronQuestions) and the bespoke Tier-3 Lorekeep-Reason eval.
 

{lorekeep-0.6.0 → lorekeep-0.7.0}/docs/README.md

@@ -16,7 +16,7 @@ Concepts and design — how the system fits together.
 - [Agent](architecture/agent.md) — autonomous agent: daemon, trigger model, lint, resolve, suggest, cost profile.
 - [Permission model](architecture/permission.md) — namespace visibility rules, deny-by-default, the single `ScopedGraph` chokepoint.
 - [Temporal model](architecture/temporal.md) — `valid_from`/`valid_to`, `at_time` / `history` / `changes`.
-- [Serve & MCP](architecture/serve-mcp.md) — 8 read + 5 write MCP tools, lazy-reload, journal-based writes, agent integration, sync.
+- [Serve & MCP](architecture/serve-mcp.md) — 9 read + 5 write MCP tools, lazy-reload, journal-based writes, agent integration, sync.
 - [Testing & evaluation](architecture/evaluation.md) — the three-tier eval strategy and scope.
 
 ## Guides

{lorekeep-0.6.0 → lorekeep-0.7.0}/docs/architecture/data-model.md

@@ -102,7 +102,7 @@ Each component has one responsibility, a clear input/output interface, and is te
 | `perm/ns` | `allowed_ns` (set) | filter / guard | **Single permission chokepoint.** Every store query passes through here. |
 | `store/fts` (optional) | `facts.jsonl` | FTS cache | FTS5 over node text/props for text search. Local, gitignored, rebuilt from `facts.jsonl`. Falls back to in-memory scan if absent. |
 | `integrations/*` | agent type, scope, ns | config file + snippet | Write Claude Code / Cursor / Codex MCP config; emit agent-memory text. |
-| `mcp_server` | store + perm | 8 read + 5 write MCP tools | FastMCP server, stdio (default). Loads store once; enforces permission per request. Write tools append to journals. |
+| `mcp_server` | store + perm | 9 read + 5 write MCP tools | FastMCP server, stdio (default). Loads store once; enforces permission per request. Write tools append to journals. |
 
 ### Dependency order
 

{lorekeep-0.6.0 → lorekeep-0.7.0}/docs/architecture/serve-mcp.md

@@ -12,7 +12,7 @@ The serve chain loads `facts.jsonl` once and exposes it to coding agents over MC
 - **Lazy-reload:** every query stats `facts.jsonl`'s mtime; if it changed (after compile or resolve) the graph is rebuilt automatically. Connect the server once — graph updates are visible without reconnecting. Reconnect is only needed for code or scope (`.mcp.json` `LOREKEEP_NS`) changes.
 - **Journals:** write tools append to `pending/<ns>/journal.jsonl`; facts enter the graph on the next resolve pass, not immediately. This avoids write conflicts and keeps the read path fast.
 
-## Read tools (8 tools, scoped)
+## Read tools (9 tools, scoped)
 
 | Tool | Purpose |
 |---|---|

{lorekeep-0.6.0 → lorekeep-0.7.0}/docs/guides/getting-started.md

@@ -133,8 +133,8 @@ uvx lorekeep mcp add --agent opencode --ns backend
 
 Supported agents: `claude`, `cursor`, `codex`, `opencode`.
 
-Restart the agent → the 13 Lorekeep tools (8 read: `search`, `get_node`,
-`neighbors`, `at_time`, `history`, `changes`, `list_namespaces`, `schema`;
+Restart the agent → the 14 Lorekeep tools (9 read: `search`, `get_node`,
+`neighbors`, `at_time`, `history`, `changes`, `list_namespaces`, `schema`, `meta`;
 5 write: `propose_fact`, `link_facts`, `flag_contradiction`, `update_fact`,
 `suggest_improvement`) are
 available, scoped to `backend` (+ `public`). See

{lorekeep-0.6.0 → lorekeep-0.7.0}/docs/guides/serve.md

@@ -42,12 +42,56 @@ LOREKEEP_HOME=~/kb-work uvx lorekeep init
 LOREKEEP_HOME=~/kb-work uvx lorekeep compile
 ```
 
-## Read tools (8 tools, scoped)
+## Read tools (9 tools, scoped)
 
 `search`, `get_node`, `neighbors`, `at_time`, `history`, `changes`,
-`list_namespaces`, `schema`. Results are filtered to `LOREKEEP_NS`; cross-namespace
+`list_namespaces`, `schema`, `meta`. Results are filtered to `LOREKEEP_NS`; cross-namespace
 edges are hidden unless both endpoints are visible.
 
+### `meta(topic="")` — scope awareness
+
+Agents call `meta()` to decide whether to query the graph or work from memory:
+
+```json
+{
+  "nodes": 42,
+  "edges": 18,
+  "node_types": {"service": 30, "decision": 12},
+  "edge_types": {"depends_on": 15, "decided_by": 3},
+  "namespaces": ["backend", "frontend", "public"],
+  "provenance": {"curator": 38, "agent": 4},
+  "freshness": {
+    "oldest": "2024-01-15",
+    "newest": "2026-06-20",
+    "expired": 2
+  },
+  "compile": {
+    "run_id": "abc123",
+    "compiled_at": "2026-06-30T01:27:59Z",
+    "merged_count": 4,
+    "quarantined_count": 1
+  },
+  "pending": 7
+}
+```
+
+Pass `topic` to check coverage for a specific subject:
+
+```json
+{
+  "coverage": {
+    "topic": "payments",
+    "matching_nodes": 3,
+    "matching_types": {"service": 2, "decision": 1},
+    "node_ids": ["svc:payments-api", "dec:adr-007", "svc:payments-worker"]
+  }
+}
+```
+
+**Provenance signal:** `provenance.curator` counts nodes with `src` (compiled from raw docs, higher trust). `provenance.agent` counts nodes without `src` (agent-proposed via journal, lower trust). If most facts are agent-proposed, the agent should verify before relying on them.
+
+**Freshness signal:** `freshness.expired` counts nodes whose `valid_to` has passed. `compile.compiled_at` shows when the graph was last rebuilt. `pending` shows unresolved agent proposals.
+
 ## Write tools (5 tools, journal-based)
 
 Agents contribute knowledge during conversation at **zero LLM cost**. Facts

{lorekeep-0.6.0 → lorekeep-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lorekeep"
-version = "0.6.0"
+version = "0.7.0"
 description = "Temporal knowledge graph for AI agents via MCP"
 readme = "README.md"
 license = {text = "MIT"}

{lorekeep-0.6.0 → lorekeep-0.7.0}/src/lorekeep/__init__.py

@@ -1,3 +1,3 @@
 """Lorekeep — temporal knowledge graph for AI agents via MCP."""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{lorekeep-0.6.0 → lorekeep-0.7.0}/src/lorekeep/cli.py

@@ -10,6 +10,7 @@ import typer
 from lorekeep import __version__
 from lorekeep.compile.providers import LiteLLMProvider
 from lorekeep.config import Config, load_config
+from lorekeep.models import now_iso
 from lorekeep.pipeline import compile_graph
 from lorekeep.paths import resolve_paths
 from lorekeep.defaults import DEFAULT_CONFIG_YAML, DEFAULT_SCHEMA, PROVIDER_PRESETS
@@ -214,6 +215,7 @@ def resolve(
         edge_count=len(resolved.edges),
         run_id="resolve",
         facts_hash="",
+        compiled_at=now_iso(),
         merged_count=merged.merge_count,
         quarantined_count=merged.quarantine_count,
         flagged_count=merged.flagged_count,
@@ -1236,6 +1238,7 @@ def _do_auto_resolve(out_dir: Path, pending_dir: Path, wiki_dir: Path | None = N
                 node_count=len(resolved.nodes),
                 edge_count=len(resolved.edges),
                 run_id="auto-resolve", facts_hash="",
+                compiled_at=now_iso(),
                 merged_count=merged.merge_count,
                 quarantined_count=merged.quarantine_count,
                 flagged_count=merged.flagged_count,