From 3b5cd2e7713171a08e093c71245312a4a50f5edd Mon Sep 17 00:00:00 2001 From: n1kt4r Date: Thu, 15 Oct 2026 15:40:54 +0500 Subject: [PATCH] EXAMPLES: replace illustrative values with verified real output; add values disclaimer --- EXAMPLES.md | 83 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 28 deletions(-) diff --git a/EXAMPLES.md b/EXAMPLES.md index 517e14d..1fac05d 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -3,6 +3,13 @@ Concrete examples of how the agent should interact with the knowledge base. All calls go through the MCP tools `mcp__pegas-memory__*`. +> **On the values.** Tool names, argument names, response **shapes** and behaviour are exact — +> verified against the running service on 2026-10-15. Concrete numbers (atom/doc/gap counts, +> ids, similarity scores, `doc_id`) are a **snapshot** taken at that moment and change as the +> base grows; every example that captures real output is marked *actual*, and every example that +> mutates data shows an *illustrative* id (marked accordingly). The **shape is stable, the values +> are not** — always call the tool instead of quoting a remembered number. + --- ## Example 1 — "What do you know?" (the most common mistake) @@ -28,13 +35,15 @@ That is 2 wrong calls + 4 wasted web searches. memory_stats() ``` -**Result:** +**Result** (actual, 2026-10-15): ```json -{"atoms": 82, "documents": 6, "open_gaps": 0} +{"atoms": 89, "documents": 6, "open_gaps": 3} ``` -**Answer:** "My knowledge base holds 82 atoms across 6 documents; no open research gaps." +**Answer:** "My knowledge base holds 89 atoms across 6 documents; 3 open research gaps." + +> Counts grow as the base grows — always call the tool, never quote a remembered number. --- @@ -48,22 +57,27 @@ memory_stats() memory_search("Memgraph", top_k = 5) ``` -**Result:** +**Result** (actual, abridged): ```json {"query": "Memgraph", "hits": [ - {"id": 4, "score": 0.91, "type": "fact", - "claim": "Memgraph is an in-memory graph database compatible with Cypher", - "status": "verified", "confidence": 1.0, "doc_id": 1}, - {"id": 9, "score": 0.87, "type": "definition", - "claim": "Memgraph is an in-memory graph DB using Cypher and Bolt", - "status": "candidate", "confidence": 0.9, "doc_id": 2} + {"id": 171, "score": 0.854, "type": "text", + "claim": "Memgraph Lab provides graph visualization and execution of ad hoc queries for data understanding.", + "status": "candidate", "confidence": 0.9, "doc_id": 13}, + {"id": 168, "score": 0.843, "type": "fact", + "claim": "Memgraph documentation is available at memgraph.com/docs.", + "status": "candidate", "confidence": 0.95, "doc_id": 13}, + {"id": 128, "score": 0.835, "type": "definition", + "claim": "Memgraph serves as the graph engine for GraphRAG pipelines, AI memory systems...", + "status": "candidate", "confidence": 0.9, "doc_id": 10} ]} ``` -**Answer:** "Yes — an in-memory graph database, Cypher-compatible, faster than Neo4j on -analytical workloads. One of these atoms is still `candidate` (not cross-confirmed yet)." +**Answer:** "The base holds several Memgraph atoms (Lab visualization, docs location, role as a +GraphRAG engine). All are still `candidate` — cross-confirm before treating them as verified." + +> IDs, scores and `doc_id` change with every ingest. The *shape* is stable; the values are not. If nothing is found → say "not in the knowledge base" and offer to research it. @@ -103,10 +117,15 @@ memory_store( ) ``` -**Result:** +**Result** (illustrative — the id is assigned by the database): ```json -{"atom_id": 117, "created": true} +{"atom_id": 172, "created": true} +``` + +If the same claim already exists, the deduplicator returns the existing id instead: +```json +{"atom_id": 168, "created": false, "duplicate_of": 168} ``` ### ✗ Wrong @@ -127,10 +146,10 @@ Raw articles are not atoms. Use `memory_ingest` to distill a document, or write memory_ingest(url = "https://example.com/graph-dbs") ``` -**Result:** +**Result** (illustrative shape — values depend on the source): ```json -{"doc_id": 7, "chunks": 5, "atoms_created": 14, +{"doc_id": 14, "chunks": 5, "atoms_created": 14, "atoms_skipped": 3, "duplicates": 2} ``` @@ -149,12 +168,12 @@ memory_ingest(url = "https://example.com/graph-dbs") memory_verify(atom_id = 113, self_critique = true) ``` -**Result:** +**Result** (illustrative — depends on the atom and the current base): ```json -{"atom_id": 113, "verdict": "corroborates", "corroborations": 2, - "new_status": "verified", "new_confidence": 1.0, - "reason": "Confirmed by two independent sources (doc 1 and doc 3)."} +{"atom_id": 8, "verdict": "duplicate", "corroborations": 1, + "new_status": "stale", "new_confidence": 1.0, + "reason": "Repeats an already known fact about Qdrant from another source."} ``` Verdicts: `new` · `duplicate` (→ stale) · `corroborates` (→ verified) · `contradicts` (→ contested). @@ -182,12 +201,16 @@ Then: memory_search_code("upsert") ``` -**Result:** +**Result** (actual, abridged): ```json -{"symbols": [ - {"repo": "pegas-memory", "path": "db.py", "symbol_name": "upsert_atom", - "kind": "function", "line_start": 34} +{"query": "upsert", + "symbols": [ + {"id": 11, "repo": "pegas-memory", + "path": "/home/neo/workspace/pegas-memory/pegas_memory/memgraph_store.py", + "symbol_name": "upsert_link", "kind": "function", "line_start": 26}, + {"id": 83, "repo": "pegas-memory", "path": "memgraph_store.py", + "symbol_name": "upsert_link", "kind": "function"} ]} ``` @@ -206,17 +229,21 @@ memory_infer(if = ["depends_on", "depends_on"], then = "depends_on") memory_query_graph(kind = "depends_on", top_k = 10) ``` -**Result:** +**Result** (actual, abridged): ```json {"kind": "depends_on", "edges": [ - {"src": "db", "dst": "psycopg", "kind": "depends_on", "inferred": true}, - {"src": "embedding", "dst": "httpx", "kind": "depends_on", "inferred": true} + {"src": "code_symbols", "dst": "hashlib", "kind": "depends_on", "inferred": true}, + {"src": "code_symbols", "dst": "tree_sitter","kind": "depends_on", "inferred": true}, + {"src": "db", "dst": "psycopg", "kind": "depends_on", "inferred": true} ], - "nodes": 176, "code_symbols": 162} + "nodes": 89, "code_symbols": 162} ``` +> `"inferred": true` marks an edge produced by logical inference, not extracted from source. +> Empty-ish targets like `"."` come from relative imports (`from . import x`) — harmless. + --- ## Anti-patterns (do not do this)