neo/pegas-memory
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

EXAMPLES: replace illustrative values with verified real output; add values disclaimer

Browse Source
This commit is contained in:
n1kt4r committed 2026-10-15 15:40:54 +05:00
1 parent a82d8c5a21
commit 3b5cd2e771
1 file changed
+55 -28
Download Patch File Download Diff File Expand all files Collapse all files
EXAMPLES.md
+55 -28
View File
@@ -3,6 +3,13 @@
Concrete examples of how the agent should interact with the knowledge base. Concrete examples of how the agent should interact with the knowledge base.
All calls go through the MCP tools `mcp__pegas-memory__*`. 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) ## 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() memory_stats()
``` ```
**Result:** **Result** (actual, 2026-10-15):
```json ```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) memory_search("Memgraph", top_k = 5)
``` ```
**Result:** **Result** (actual, abridged):
```json ```json
{"query": "Memgraph", {"query": "Memgraph",
"hits": [ "hits": [
{"id": 4, "score": 0.91, "type": "fact", {"id": 171, "score": 0.854, "type": "text",
"claim": "Memgraph is an in-memory graph database compatible with Cypher", "claim": "Memgraph Lab provides graph visualization and execution of ad hoc queries for data understanding.",
"status": "verified", "confidence": 1.0, "doc_id": 1}, "status": "candidate", "confidence": 0.9, "doc_id": 13},
{"id": 9, "score": 0.87, "type": "definition", {"id": 168, "score": 0.843, "type": "fact",
"claim": "Memgraph is an in-memory graph DB using Cypher and Bolt", "claim": "Memgraph documentation is available at memgraph.com/docs.",
"status": "candidate", "confidence": 0.9, "doc_id": 2} "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 **Answer:** "The base holds several Memgraph atoms (Lab visualization, docs location, role as a
analytical workloads. One of these atoms is still `candidate` (not cross-confirmed yet)." 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. 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 ```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 ### ✗ 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") memory_ingest(url = "https://example.com/graph-dbs")
``` ```
**Result:** **Result** (illustrative shape — values depend on the source):
```json ```json
{"doc_id": 7, "chunks": 5, "atoms_created": 14, {"doc_id": 14, "chunks": 5, "atoms_created": 14,
"atoms_skipped": 3, "duplicates": 2} "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) memory_verify(atom_id = 113, self_critique = true)
``` ```
**Result:** **Result** (illustrative — depends on the atom and the current base):
```json ```json
{"atom_id": 113, "verdict": "corroborates", "corroborations": 2, {"atom_id": 8, "verdict": "duplicate", "corroborations": 1,
"new_status": "verified", "new_confidence": 1.0, "new_status": "stale", "new_confidence": 1.0,
"reason": "Confirmed by two independent sources (doc 1 and doc 3)."} "reason": "Repeats an already known fact about Qdrant from another source."}
``` ```
Verdicts: `new` · `duplicate` (→ stale) · `corroborates` (→ verified) · `contradicts` (→ contested). Verdicts: `new` · `duplicate` (→ stale) · `corroborates` (→ verified) · `contradicts` (→ contested).
@@ -182,12 +201,16 @@ Then:
memory_search_code("upsert") memory_search_code("upsert")
``` ```
**Result:** **Result** (actual, abridged):
```json ```json
{"symbols": [ {"query": "upsert",
{"repo": "pegas-memory", "path": "db.py", "symbol_name": "upsert_atom", "symbols": [
"kind": "function", "line_start": 34} {"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) memory_query_graph(kind = "depends_on", top_k = 10)
``` ```
**Result:** **Result** (actual, abridged):
```json ```json
{"kind": "depends_on", {"kind": "depends_on",
"edges": [ "edges": [
{"src": "db", "dst": "psycopg", "kind": "depends_on", "inferred": true}, {"src": "code_symbols", "dst": "hashlib", "kind": "depends_on", "inferred": true},
{"src": "embedding", "dst": "httpx", "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) ## Anti-patterns (do not do this)