Sync: local changes as of 2026-07-29T22:48:00+02:00
This commit is contained in:
parent
f879f859e3
commit
be41d4877c
12 changed files with 243 additions and 24 deletions
|
|
@ -63,6 +63,13 @@ libraries, concepts, systems. Create entity pages at
|
|||
relationships between entities — `uses`, `depends_on`, `caused`,
|
||||
`contradicts`, `supersedes` — as edge data in `wiki/graph/edges.json`.
|
||||
|
||||
For recurring teams, clients, systems, or initiatives, consider whether a
|
||||
plain project scope page under `wiki/projects/<name>.md` would make future
|
||||
queries easier to route. A scope page should list when to use it, included
|
||||
wiki/entity/source paths, exclusions, and refresh hints. Create one only
|
||||
when the source material shows a real repeated scope; don't manufacture
|
||||
scopes for one-off facts.
|
||||
|
||||
### Step 4 — Synthesize pages
|
||||
|
||||
Convert the core knowledge into clean, modular Markdown files. Every page
|
||||
|
|
@ -78,6 +85,20 @@ gets frontmatter with:
|
|||
`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content
|
||||
kind (person, project, concept, library, decision, playbook, ...).
|
||||
|
||||
For long conversations, meeting notes, transcripts, or chat exports, use a
|
||||
structured distillation before writing the final page:
|
||||
- `Question` or searchable problem statement, when there is one.
|
||||
- `Summary` of the thread/note.
|
||||
- `Resolution` or `Decision`, if the material contains one.
|
||||
- `Systems and code references` mentioned.
|
||||
- `People involved` or apparent owners/experts.
|
||||
- `High-signal excerpts` for dense technical paragraphs or consecutive
|
||||
messages that would be lost in a single summary.
|
||||
|
||||
If a high-signal excerpt is substantial enough to answer future questions
|
||||
on its own, keep it as its own section or linked page rather than burying
|
||||
it inside a broad transcript summary.
|
||||
|
||||
### Step 5 — Link and cross-reference
|
||||
|
||||
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard
|
||||
|
|
@ -98,6 +119,11 @@ If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately
|
|||
create that subdirectory's `index.md` per the Recursive Index & Log
|
||||
Convention.
|
||||
|
||||
If this step creates or updates a project scope under `wiki/projects/`,
|
||||
also update `wiki/projects/index.md`. If ingest closes a previously
|
||||
recorded question in `wiki/query-gaps.md`, move that entry from Open to
|
||||
Resolved and mention the page or source that now answers it.
|
||||
|
||||
### Step 7 — Remind to review and sync
|
||||
|
||||
This is always the last step, every time this skill runs and made any
|
||||
|
|
|
|||
|
|
@ -61,8 +61,13 @@ Do **not** use this skill for:
|
|||
|
||||
Same cascade order as CLAUDE.md/AGENTS.md §5, first match wins:
|
||||
1. `wiki/index.md` — match the question against the **Use when** column.
|
||||
2. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
||||
3. If nothing local matches: each `linked/<name>/` index (alphabetical),
|
||||
2. `wiki/projects/index.md` — if a project scope matches the question,
|
||||
use that project's listed pages, entity pages, raw/archive sources,
|
||||
connector-backed libs, outputs, and graph areas as the first search
|
||||
boundary. A project scope narrows the first pass only; it never hides
|
||||
the rest of the cascade.
|
||||
3. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
||||
4. If nothing local matches: each `linked/<name>/` index (alphabetical),
|
||||
then each connector-backed `libs/<name>/entities/index.md` — for a
|
||||
connector-backed lib this means its *generated* index (both the
|
||||
Documents and the Entities & Processes sections `ckb-index-external`
|
||||
|
|
@ -80,6 +85,14 @@ only tangential can still be hiding the exact fact needed in its body or
|
|||
its Sources. Keep the shortlist to what's plausibly relevant; this isn't
|
||||
"open everything," it's "don't stop at one."
|
||||
|
||||
If index/TLDR matching is not enough, run a local hybrid pass before
|
||||
giving up: use `rg` for exact tokens across `wiki/`, `raw/archive/`,
|
||||
`outputs/`, and readable upstream indexes; combine those hits with
|
||||
project-scope matches, entity/title/TLDR matches, graph proximity,
|
||||
freshness, confidence, and quality. Prefer exact text matches for error
|
||||
strings, commands, flags, filenames, hostnames, IDs, and other literals;
|
||||
prefer entity/semantic matches for paraphrased questions.
|
||||
|
||||
### Step 3 — Walk the graph for anything the shortlist missed
|
||||
|
||||
If a shortlisted page has edges in `wiki/graph/edges.json` (or a
|
||||
|
|
@ -87,7 +100,22 @@ connector's own `graph/edges.json`), follow `depends_on`/`uses`/`caused`
|
|||
edges one hop out — the same way §5 Step 4 already directs — to catch a
|
||||
connected page the index text match alone wouldn't have surfaced.
|
||||
|
||||
### Step 4 — Follow every page on the shortlist to its source before answering from it
|
||||
### Step 4 — Expand local context and build an evidence packet
|
||||
|
||||
For every result that might ground the answer, keep a small evidence
|
||||
packet with:
|
||||
- source path or connector resource
|
||||
- matched claim or short excerpt
|
||||
- source date or `last_updated`
|
||||
- freshness/confidence/quality signals, when available
|
||||
- project-scope or graph relationship hints, when relevant
|
||||
|
||||
When a match is a section, heading, or snippet inside a larger Markdown
|
||||
file, include nearby headings/paragraphs before deciding what it means.
|
||||
Avoid answering from an isolated fragment when the neighboring context
|
||||
changes the interpretation.
|
||||
|
||||
### Step 5 — Follow every page on the shortlist to its source before answering from it
|
||||
|
||||
This is the step this skill exists to enforce. For each page on the
|
||||
shortlist that will actually ground part of the answer:
|
||||
|
|
@ -120,7 +148,7 @@ deck doesn't need a full read every time, just enough (search for the
|
|||
name/topic, read the surrounding context) to confirm the point actually
|
||||
being used.
|
||||
|
||||
### Step 5 — Reconcile and answer
|
||||
### Step 6 — Reconcile and answer
|
||||
|
||||
If the source confirms the index, answer normally — but note what
|
||||
grounded it (e.g. "per the kickoff transcript cited in
|
||||
|
|
@ -136,7 +164,11 @@ mid-answer unless the user asks for that separately.
|
|||
|
||||
If no page anywhere is even plausibly relevant, say so — don't verify
|
||||
against a source that has nothing to do with the question just to appear
|
||||
thorough, and don't fabricate an answer either.
|
||||
thorough, and don't fabricate an answer either. For durable missing
|
||||
knowledge, add or propose a short `wiki/query-gaps.md` entry with the
|
||||
question, date, search areas tried, and the smallest missing source/page
|
||||
that would close the gap. If you edit `wiki/query-gaps.md`, update
|
||||
`wiki/log.md` immediately.
|
||||
|
||||
## Edge cases
|
||||
|
||||
|
|
@ -169,8 +201,9 @@ thorough, and don't fabricate an answer either.
|
|||
- **Nothing in the index is even plausibly relevant** — say the knowledge
|
||||
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
|
||||
material) or `ckb-index-external` (for a connector-backed source) if
|
||||
that seems like the actual gap. Don't stretch a weak match into an
|
||||
answer just to have one.
|
||||
that seems like the actual gap. For durable gaps, record or propose a
|
||||
`wiki/query-gaps.md` entry. Don't stretch a weak match into an answer
|
||||
just to have one.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
31
AGENTS.md
31
AGENTS.md
|
|
@ -40,6 +40,8 @@ The root directory contains exactly seven top-level entries. You must maintain t
|
|||
│ ├── overview.md # High-level map of the knowledge base.
|
||||
│ ├── log.md # AGENT LOG. Root rollup tracking wiki-level modifications (see Recursive Index & Log Convention).
|
||||
│ ├── error-book.md # AGENT MAINTAINED. Records compilation errors and derived constraints.
|
||||
│ ├── query-gaps.md # AGENT MAINTAINED. Failed or missing-answer questions that should drive future ingest.
|
||||
│ ├── projects/ # AGENT POPULATED. Optional local query scopes for teams, clients, systems, or initiatives.
|
||||
│ ├── entities/ # AGENT POPULATED. Typed entity pages (people, projects, concepts, libraries). Has its own index.md.
|
||||
│ └── graph/ # AGENT MAINTAINED. Edge lists and relationship data for the knowledge graph. Has its own index.md.
|
||||
└── workload/ # MANAGED BY AGENT. Summaries of discussions and decisions.
|
||||
|
|
@ -70,7 +72,7 @@ This avoids blind filesystem scans and uses the index as a curated table of cont
|
|||
### Recursive Index & Log Convention
|
||||
Index-First Navigation only works if subdirectory indexes actually exist. Maintain them as follows:
|
||||
|
||||
- Every `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory.
|
||||
- Every `wiki/` subdirectory that groups multiple pages (`projects/`, `entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory.
|
||||
- A subdirectory may also keep its own `log.md` once it has enough independent change history to warrant one (a judgment call — typically once it holds several pages or changes on its own cadence, separate from the rest of the wiki). Entries follow the same reverse-chronological format as Rule B.
|
||||
- The root `wiki/log.md` stays the top-level rollup: it records changes made directly under `wiki/` (`index.md`, `overview.md`, `error-book.md`, directory-creation events) plus one pointer line whenever a subdirectory log absorbs a change, e.g. `- See wiki/entities/log.md for entity-page changes on this date.` Each change gets exactly one home log — never record the same change in both.
|
||||
- The same convention applies verbatim inside a connector-backed `libs/<name>/` (§4) — its generated `index.md`/`entities/index.md`/`graph/index.md`/`log.md` mirror this pattern exactly, scoped entirely to that one connector. Its `log.md` is independent of `wiki/log.md` — never record a connector-indexing change in both.
|
||||
|
|
@ -118,7 +120,7 @@ retention: high|medium|low # How aggressively to deprioritize when old
|
|||
- **`retention`** — `low` pages may be archived or deprioritized after the freshness window expires.
|
||||
|
||||
### Schema Versioning
|
||||
`wiki/index.md` (only) carries an additional frontmatter field, `kb_schema_version` (e.g. `"1.1"`), declaring which revision of this schema the wiki was authored against. Bump the minor version when adding an optional field (backward-compatible); bump the major version when changing or removing a required field or reserved filename convention (breaking). Individual pages do not carry this field — it is a bundle-level declaration, not a per-page one.
|
||||
`wiki/index.md` (only) carries an additional frontmatter field, `kb_schema_version` (e.g. `"1.2"`), declaring which revision of this schema the wiki was authored against. Bump the minor version when adding an optional field or optional reserved wiki scaffold (backward-compatible); bump the major version when changing or removing a required field or existing reserved filename convention (breaking). Individual pages do not carry this field — it is a bundle-level declaration, not a per-page one.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -139,10 +141,27 @@ When the user says "Index external sources" (or "index libs", "refresh the exter
|
|||
When answering a question or researching a topic:
|
||||
|
||||
1. **Read the index** — `wiki/index.md` first. Match query keywords against **Use when** triggers.
|
||||
2. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop.
|
||||
3. **Load full pages** — only if the TLDR was insufficient.
|
||||
4. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?").
|
||||
5. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout.
|
||||
2. **Apply local project scope when obvious** — if `wiki/projects/index.md` has a matching project scope, use that scope's listed wiki pages, entities, raw/archive sources, libs, and graph areas as the first search area. If no scope matches, continue with the whole cascade.
|
||||
3. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop after verifying the source when the answer matters.
|
||||
4. **Run local hybrid search when index/TLDR routing is insufficient** — combine exact text search (`rg` over `wiki/`, `raw/archive/`, `outputs/`, and readable upstream indexes) with index/TLDR matches, freshness metadata, confidence, and graph proximity. Prefer exact matches for error strings, flags, IDs, filenames, commands, and hostnames; prefer semantic/entity matches for paraphrased questions.
|
||||
5. **Load full pages with context expansion** — only if TLDRs were insufficient. When a section or snippet matches, include neighboring headings/paragraphs so the answer is grounded in a complete local context rather than an isolated fragment.
|
||||
6. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?").
|
||||
7. **Build an evidence packet** — before answering, normalize the supporting material into source path, matched claim, source date or `last_updated`, confidence/quality/freshness, and relationship/project-scope hints. Use this internally to compare evidence and cite the strongest sources.
|
||||
8. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout.
|
||||
9. **Record durable gaps** — if no page or source plausibly answers the query, add or propose a short entry in `wiki/query-gaps.md` with the question, date, attempted search areas, and the smallest missing source/page that would close the gap. If you edit `wiki/query-gaps.md`, log it immediately in `wiki/log.md`.
|
||||
|
||||
### Project Scope Pages
|
||||
Project scopes are optional local-first retrieval aids, inspired by the "project" concept in large knowledge systems but implemented as plain Markdown. A project page lives at `wiki/projects/<name>.md` with normal frontmatter (`type: project_scope`) and should include:
|
||||
|
||||
- `## Use when` — keywords or situations that should route to this scope.
|
||||
- `## Scope` — relevant wiki pages, entity pages, graph nodes, raw/archive paths, outputs, linked KBs, and libs.
|
||||
- `## Exclusions` — sources that look related but should not be searched by default.
|
||||
- `## Refresh hints` — which sources are likely to go stale first and how often to re-check them.
|
||||
|
||||
Scopes narrow the first pass only; they never hide the rest of the cascade when the scoped search is insufficient.
|
||||
|
||||
### Long-Note Distillation
|
||||
When ingesting long conversations, meeting notes, transcripts, or chat exports, prefer a structured distillation over embedding or summarizing raw text as one blob. Capture the searchable question, short summary, resolution/decision, systems or code references, people involved, and high-signal excerpts. For very long notes, preserve important "bursts" — consecutive paragraphs or messages with dense technical signal — as separate sections or linked pages when they would otherwise be lost in a thread-level summary.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
31
MANUAL.md
31
MANUAL.md
|
|
@ -172,6 +172,21 @@ ingest incorporates it. This keeps the wiki demand-driven: it grows around
|
|||
what you actually ask, not everything that could theoretically be written
|
||||
down.
|
||||
|
||||
Durable misses can also be tracked in `wiki/query-gaps.md`. A good gap
|
||||
entry is tiny: the question, where the agent looked, and the smallest
|
||||
source or page that would make the answer available next time.
|
||||
|
||||
### D. Create a local project scope
|
||||
|
||||
When a topic, client, system, or initiative comes up often, ask:
|
||||
|
||||
> "Create a project scope for payments integration."
|
||||
|
||||
The agent creates or updates a plain Markdown page under `wiki/projects/`
|
||||
listing the pages, entities, raw/archive files, connector indexes, and graph
|
||||
areas that should be searched first for that scope. You still keep one
|
||||
local wiki; this just gives repeated questions a better starting area.
|
||||
|
||||
---
|
||||
|
||||
## 3. Keeping it tidy
|
||||
|
|
@ -346,11 +361,17 @@ Just ask, in plain language:
|
|||
|
||||
> "What do we know about the Q3 migration risk?"
|
||||
|
||||
The agent reads `wiki/index.md` first to find relevant pages, checks their
|
||||
one-line `tldr` before loading the full page, walks the knowledge graph for
|
||||
connected facts, and falls back to `linked/`/`libs/` if the local wiki has
|
||||
nothing. You get an answer grounded in what's actually written down, not a
|
||||
guess.
|
||||
The agent reads `wiki/index.md` first to find relevant pages. If a matching
|
||||
project scope exists under `wiki/projects/`, it searches that scope first.
|
||||
Then it checks one-line `tldr` fields, runs exact local search for literal
|
||||
tokens when needed, expands context around matching sections, walks the
|
||||
knowledge graph for connected facts, and falls back to `linked/`/`libs/` if
|
||||
the local wiki has nothing. You get an answer grounded in what's actually
|
||||
written down, not a guess.
|
||||
|
||||
When there is still no answer, the agent should tell you what is missing
|
||||
and either add/propose a short entry in `wiki/query-gaps.md` or suggest the
|
||||
smallest source to drop into `raw/inbox/`.
|
||||
|
||||
### Learn from the wiki
|
||||
|
||||
|
|
|
|||
44
README.md
44
README.md
|
|
@ -31,6 +31,8 @@ worked examples for every use case — see [MANUAL.md](MANUAL.md)
|
|||
│ ├── overview.md # High-level map
|
||||
│ ├── log.md # Root rollup change log
|
||||
│ ├── error-book.md # Compilation errors & derived constraints
|
||||
│ ├── query-gaps.md # Failed or missing-answer questions for future ingest
|
||||
│ ├── projects/ # Optional local query scopes
|
||||
│ ├── entities/ # Typed entity pages (people, projects, concepts) + own index.md
|
||||
│ └── graph/ # Edge lists and relationship data + own index.md
|
||||
└── workload/ # Session summaries & decisions
|
||||
|
|
@ -72,6 +74,12 @@ Implemented as a Claude Code Skill — see
|
|||
actually invoked. Distinct from the `ckb-sync-changes` skill, which is a
|
||||
pure git-level operation with no wiki synthesis.
|
||||
|
||||
For long conversations, meeting notes, transcripts, or chat exports, ingest
|
||||
uses a structured distillation rather than treating the whole file as one
|
||||
undifferentiated blob: searchable question, short summary, resolution or
|
||||
decision, systems/code references, people involved, and high-signal excerpts
|
||||
that deserve to stay findable on their own.
|
||||
|
||||
### Lazy-Loading Index with "Use When" Triggers
|
||||
`wiki/index.md` is a routing table. Each entry has a **Use when** column
|
||||
listing trigger keywords. The agent reads the index first (stays in context),
|
||||
|
|
@ -83,6 +91,40 @@ Every page carries a one-sentence `tldr` in frontmatter. When querying, the
|
|||
agent reads TLDRs first. If the TLDR already answers the question, the full
|
||||
body is never loaded. Fallback chain: TLDR → body → raw source.
|
||||
|
||||
### Local Project Scopes
|
||||
For recurring teams, clients, systems, or initiatives, the wiki can keep
|
||||
plain Markdown scope pages under `wiki/projects/`. A scope page lists the
|
||||
wiki pages, entities, raw/archive sources, connector-backed libs, outputs,
|
||||
and graph areas that should be searched first for that project. This gives
|
||||
the same practical benefit as a project workspace in a larger retrieval
|
||||
system while staying local, transparent, and editable with any text editor.
|
||||
|
||||
Scopes only narrow the first pass. If the scoped search does not answer the
|
||||
question, the agent falls back to the full cascade.
|
||||
|
||||
### Local Hybrid Retrieval
|
||||
When index/TLDR routing is not enough, the agent can combine several local
|
||||
signals before answering:
|
||||
- exact text search with `rg` for error strings, commands, flags, filenames,
|
||||
hostnames, ticket IDs, and other literal tokens
|
||||
- semantic/entity matches from page titles, TLDRs, project scopes, and graph
|
||||
relationships
|
||||
- freshness and confidence metadata, so stale or weak pages are treated with
|
||||
care
|
||||
- context expansion around a matched section, so answers are grounded in the
|
||||
neighboring headings and paragraphs rather than a lone snippet
|
||||
|
||||
The result is normalized internally as an evidence packet: source path,
|
||||
matched claim, date/freshness, confidence/quality, and relationship or scope
|
||||
hints. No server, vector database, or dedicated client is required.
|
||||
|
||||
### Query Gaps
|
||||
If the cascade cannot answer a question, the agent records or proposes a
|
||||
short entry in `wiki/query-gaps.md`: what was asked, where it looked, and the
|
||||
smallest source or page that would close the gap. This makes failed searches
|
||||
useful demand signals for the next ingest instead of disappearing into chat
|
||||
history.
|
||||
|
||||
### Page Frontmatter Schema
|
||||
Every wiki page uses YAML frontmatter. `type` is required; the rest are optional:
|
||||
|
||||
|
|
@ -109,7 +151,7 @@ retention: high|medium|low
|
|||
- **freshness_window_days** — pages older than this get flagged during lint
|
||||
- **retention** — low pages are archived after 2× freshness window
|
||||
|
||||
`wiki/index.md` alone also carries `kb_schema_version` (e.g. `"1.1"`), declaring
|
||||
`wiki/index.md` alone also carries `kb_schema_version` (e.g. `"1.2"`), declaring
|
||||
which revision of this schema the wiki was authored against — bump minor for
|
||||
additive optional fields, major for breaking changes.
|
||||
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.1.0
|
||||
1.2.0
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
kb_schema_version: "1.1"
|
||||
kb_schema_version: "1.2"
|
||||
---
|
||||
|
||||
# Knowledge Base Index
|
||||
|
|
@ -11,6 +11,8 @@ kb_schema_version: "1.1"
|
|||
| [Overview](overview.md) | High-level map of the knowledge base | Getting started, understanding the structure |
|
||||
| [Log](log.md) | Chronological record of root-level changes | Reviewing recent modifications |
|
||||
| [Error Book](error-book.md) | Known compilation errors and fixes | Debugging a bad ingest or lint issue |
|
||||
| [Projects](projects/index.md) | Optional local query scopes grouping related wiki pages, sources, libs, and graph areas | Narrowing search to a team, topic, client, system, or initiative |
|
||||
| [Query Gaps](query-gaps.md) | Questions the wiki could not answer yet, used to drive demand-driven ingest | Tracking failed searches, missing knowledge, future ingest targets |
|
||||
| [Entities](entities/index.md) | Typed entity pages (people, projects, libraries, concepts) | Looking up a specific person, project, library, or concept |
|
||||
| [Graph](graph/index.md) | Edge lists and relationship data between entities | Finding what depends on / relates to a given entity |
|
||||
|
||||
|
|
|
|||
12
wiki/log.md
12
wiki/log.md
|
|
@ -1,4 +1,16 @@
|
|||
# Wiki Change Log
|
||||
|
||||
## [2026-07-29 22:47] - [UPDATE]
|
||||
- **File Affected:** `wiki/index.md`
|
||||
- **Description:** Bumped `kb_schema_version` from `1.1` to `1.2` for the new optional project-scope and query-gap scaffold conventions.
|
||||
- **Source:** Chat conversation follow-up asking whether the wiki version was updated.
|
||||
---
|
||||
|
||||
## [2026-07-29 22:30] - [CREATE/UPDATE]
|
||||
- **File Affected:** `wiki/index.md`, `wiki/overview.md`, `wiki/projects/index.md`, `wiki/query-gaps.md`
|
||||
- **Description:** Added local-first project scope and query-gap scaffolds inspired by the Cerebras knowledge base concept while keeping the wiki file-based and agent-driven.
|
||||
- **Source:** Chat conversation comparing Cerebras knowledge base ideas to this local Cascade KB.
|
||||
---
|
||||
|
||||
All modifications to the local `wiki/` directory are recorded here
|
||||
in reverse chronological order (most recent first).
|
||||
|
|
|
|||
|
|
@ -26,6 +26,8 @@ When the same entity exists in multiple layers, the local version wins.
|
|||
│ └── inbox/ # Drop zone for unprocessed material
|
||||
├── tmp/ # Temporary files, caches (gitignored)
|
||||
├── wiki/ # Local structured wiki (agent-managed)
|
||||
│ ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
|
||||
│ ├── projects/ # Optional local query scopes
|
||||
│ ├── entities/ # Typed entity pages
|
||||
│ └── graph/ # Edge lists and relationship data
|
||||
└── workload/ # Summaries of discussions and decisions
|
||||
|
|
@ -39,6 +41,13 @@ declares `kb_schema_version` for the bundle as a whole.
|
|||
See AGENTS.md for the full schema.
|
||||
|
||||
## Recursive Indexes
|
||||
`entities/` and `graph/` each carry their own `index.md` so navigation stays
|
||||
lazy — read `wiki/index.md` first, then only descend into a subdirectory
|
||||
index if its contents are relevant to the current task.
|
||||
`entities/`, `graph/`, and optional topic folders such as `projects/` each
|
||||
carry their own `index.md` so navigation stays lazy — read `wiki/index.md`
|
||||
first, then only descend into a subdirectory index if its contents are
|
||||
relevant to the current task.
|
||||
|
||||
## Local-First Retrieval Aids
|
||||
Project scope pages in `wiki/projects/` can group related sources so a query
|
||||
starts narrow before falling back to the full cascade. `wiki/query-gaps.md`
|
||||
records questions the wiki could not answer yet, turning failed searches into
|
||||
small ingest targets.
|
||||
|
|
|
|||
8
wiki/projects/index.md
Normal file
8
wiki/projects/index.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
# Projects
|
||||
|
||||
Optional local query scopes. A project page groups related wiki pages,
|
||||
entity pages, raw/archive source paths, connector-backed libs, and graph
|
||||
areas so retrieval starts from the most relevant slice of the cascade.
|
||||
|
||||
*(No project scopes yet — create one when a topic, team, client, system, or
|
||||
initiative starts recurring often enough to deserve a default search scope.)*
|
||||
24
wiki/query-gaps.md
Normal file
24
wiki/query-gaps.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
type: log
|
||||
tldr: Local queue of questions the wiki could not answer yet, used to drive demand-driven ingest.
|
||||
confidence: 1.0
|
||||
quality: 0.8
|
||||
last_updated: 2026-07-29
|
||||
freshness_window_days: 30
|
||||
retention: medium
|
||||
---
|
||||
|
||||
# Query Gaps
|
||||
|
||||
Use this page for questions that the cascade could not answer from
|
||||
`wiki/`, `linked/`, or `libs/`. Each entry should stay short and point to
|
||||
the smallest missing source or page that would close the gap.
|
||||
|
||||
## Open
|
||||
|
||||
*(No query gaps recorded yet.)*
|
||||
|
||||
## Resolved
|
||||
|
||||
*(Move entries here after an ingest, page update, or connector index makes
|
||||
the answer available.)*
|
||||
|
|
@ -15,3 +15,26 @@
|
|||
- User asked again to commit changes.
|
||||
- Checked working-tree status; found deletions for `CLAUDE.md`, `.claude/skills/export-okf/SKILL.md`, and `.claude/skills/sync-changes/SKILL.md`.
|
||||
- Planned to commit the current working tree, including this session note.
|
||||
|
||||
## 2026-07-29 22:23 CEST
|
||||
|
||||
- User asked which ideas from the Cerebras knowledge base concept could be easily implemented in the current local wiki.
|
||||
- Re-read the current wiki scaffold and git status; identified low-effort, local-first ideas that fit Markdown files and CLI/agent workflows without requiring dedicated user software.
|
||||
|
||||
## 2026-07-29 22:44 CEST
|
||||
|
||||
- User asked to implement the selected local-first changes and update README/instruction files.
|
||||
- Added `wiki/projects/index.md` for optional project query scopes and `wiki/query-gaps.md` for durable missing-answer tracking.
|
||||
- Updated `wiki/index.md`, `wiki/overview.md`, and `wiki/log.md` to register the new scaffolds.
|
||||
- Updated `README.md`, `MANUAL.md`, `AGENTS.md`, `ckb-retrieve`, and `ckb-ingest` instructions to cover project scopes, local hybrid retrieval, evidence packets, context expansion, query-gap capture, and long-note distillation.
|
||||
|
||||
## 2026-07-29 22:47 CEST
|
||||
|
||||
- User asked whether the wiki version had been updated.
|
||||
- Confirmed it had not been bumped yet, then updated `wiki/index.md` from `kb_schema_version: "1.1"` to `"1.2"` and `VERSION` from `1.1.0` to `1.2.0`.
|
||||
- Updated README/AGENTS schema-version examples and logged the wiki schema bump in `wiki/log.md`.
|
||||
|
||||
## 2026-07-29 22:48 CEST
|
||||
|
||||
- User asked to commit changes and push to `origin`.
|
||||
- Began the `ckb-sync-changes` git-level workflow: pre-flight checks passed, `origin` was configured, and `git fetch origin` completed.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue