@digitalvibes/ai-knowledge-db 0.1.0 → 0.2.0

package/skills/knowledge-db/SKILL.md

@@ -38,6 +38,25 @@ Initialise the schema once: `npx knowledge-db init`
 
 A search for a project automatically also pulls that **client's** shared knowledge and **global** knowledge, ranked together by relevance.
 
+## Freshness — keeping facts current (IMPORTANT)
+
+Semantic search has no built-in notion of "newest", so facts that **change** (pricing, hours, contact, current offer) must be written with a stable **`key`** using `put` — not `add`. Writing the same key again supersedes the old version (kept as history) and makes the new one the only result in normal search.
+
+```bash
+# first time
+npx knowledge-db put "Basic plan is €50/mo." --key pricing.basic-plan --scope client
+# price changes — same key; search now returns only €80, €50 kept as history
+npx knowledge-db put "Basic plan is €80/mo." --key pricing.basic-plan --scope client
+```
+
+- **Use `put --key …`** for any fact that can change. The newest version always wins.
+- **Use `add`** only for accumulating notes that never need to override each other.
+- **Use `add-file --source …`** for documents — re-ingesting supersedes the prior version of that source.
+- Inspect history: `npx knowledge-db history --key pricing.basic-plan`
+- Point-in-time / include old versions: `search "…" --as-of 2026-01-01` or `search "…" --history`.
+
+Rule of thumb: **if updating it should replace the old answer, give it a `key` and use `put`.**
+
 ## CLI (preferred for quick ops)
 
 ```bash
@@ -45,9 +64,12 @@ A search for a project automatically also pulls that **client's** shared knowled
 npx knowledge-db search "what is the brand voice?"
 npx knowledge-db search "homepage hero copy" --project acme-website --json
 
-# add a fact (scope auto-derives: project if KNOWLEDGE_PROJECT_ID set, else client, else global)
+# add a free-form note (accumulates; never overrides)
 npx knowledge-db add "Client prefers sentence case for all headings." --scope client
-npx knowledge-db add "Hero CTA finalised as 'Start free'." --source decisions.md
+
+# put a CHANGEABLE fact (newer overrides older; old kept as history)
+npx knowledge-db put "Basic plan is €80/mo." --key pricing.basic-plan --scope client
+npx knowledge-db history --key pricing.basic-plan        # list all versions
 
 # add / update a file or doc idempotently (re-running replaces prior rows for that source)
 npx knowledge-db add-file ./brand/voice.md --scope client --source brand/voice.md
@@ -70,10 +92,14 @@ const kb = createKnowledgeDB(); // reads .env
 const hits = await kb.search("brand voice and tone", { limit: 5 });
 const context = hits.map((h) => h.content).join("\n\n");
 
-// store a durable fact
+// store a free-form note
 await kb.add({ content: "Client approved the green palette.", scope: "client" });
 
-// idempotently re-ingest a doc
+// store / update a CHANGEABLE fact (newer supersedes older)
+await kb.put({ key: "pricing.basic-plan", content: "Basic plan is €80/mo.", scope: "client" });
+const versions = await kb.history("pricing.basic-plan", { scope: "client" });
+
+// idempotently re-ingest a doc (supersedes prior version of this source)
 await kb.upsertSource({ content: fileText, source: "specs/sitemap.md" });
 
 await kb.close();
@@ -82,6 +108,6 @@ await kb.close();
 ## Workflow guidance for the agent
 
 1. **Before** building website copy/components or answering a "what do we know" question, run a `search` and ground your output in the results. Cite the `source` when relevant.
-2. **After** the user states a durable preference/decision ("remember…", "from now on…", "the client wants…"), `add` it with the right scope. Prefer `client` scope for anything reusable across the client's projects; `project` for this build only.
-3. When re-ingesting a known file/URL, use `add-file` / `upsertSource` (not `add`) so you don't create duplicates.
+2. **After** the user states a durable fact/decision, store it with the right scope (`client` = reusable across the client's projects, `project` = this build). Choose the verb by mutability: a **changeable** fact (pricing, hours, status) → `put` with a stable `key` so it overrides cleanly; a one-off note → `add`.
+3. When re-ingesting a known file/URL, use `add-file` / `upsertSource` (not `add`) so the prior version is superseded instead of duplicated.
 4. If a search returns nothing useful, say so rather than inventing context.