pegas-memory/EXAMPLES.md

Pegas Memory — Usage Examples

Concrete examples of how the agent should interact with the knowledge base. All calls go through the MCP tools mcp__pegas-memory__*.

---

Example 1 — "What do you know?" (the most common mistake)

User: "What's in your knowledge base?"

✗ Wrong (a real observed failure)

memory_search("knowledge base")       → []      (semantic search finds nothing useful)
read("/home/neo/workspace")           → ERROR   (it is a directory, not a file)
web_search("memory")                  → ❌ searching the INTERNET for your OWN base
web_search("knowledge base")          → ❌
web_search("atoms")                   → ❌
web_search("logical_rule")            → ❌

That is 2 wrong calls + 4 wasted web searches.

✓ Correct

memory_stats()

Result:

{"atoms": 82, "documents": 6, "open_gaps": 0}

Answer: "My knowledge base holds 82 atoms across 6 documents; no open research gaps."

---

Example 2 — "What do you know about X?"

User: "What do you know about Memgraph?"

✓ Correct

memory_search("Memgraph", top_k = 5)

Result:

{"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}
 ]}

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)."

If nothing is found → say "not in the knowledge base" and offer to research it.

---

Example 3 — Filling a knowledge gap (full loop)

User: "Research how HNSW indexing works in vector databases."

1. memory_search("HNSW")            → []                        # not known yet
2. memory_add_gap("How does HNSW work?",
                  reason = "low_coverage", priority = 0.8)
3. memory_research("How does HNSW indexing work?")
                                    → searches SearXNG, ingests sources,
                                      distills atoms, saves them
4. memory_verify()                  → cross-confirm the new atoms
5. memory_search("HNSW")            → now returns verified hits

Note: step 1 (CHECK) is mandatory — it prevents re-researching what is already known.

---

Example 4 — Storing one fact

User: "Remember that Memgraph keeps the whole graph in RAM."

✓ Correct — one atomic claim + type

memory_store(
  type       = "fact",
  claim      = "Memgraph keeps the entire graph in RAM",
  content    = "Memgraph stores the graph in memory, which is why it is faster than a disk-based graph DB on analytical workloads.",
  confidence = 0.9
)

Result:

{"atom_id": 117, "created": true}

✗ Wrong

memory_store(type = "text", content = "<entire article pasted here>")

Raw articles are not atoms. Use memory_ingest to distill a document, or write one claim.

---

Example 5 — Ingesting a document

User: "Add this article to the base: https://example.com/graph-dbs"

memory_ingest(url = "https://example.com/graph-dbs")

Result:

{"doc_id": 7, "chunks": 5, "atoms_created": 14,
 "atoms_skipped": 3, "duplicates": 2}

• duplicates — near-duplicates filtered by the semantic deduplicator (cosine ≥ 0.90).
• atoms_skipped — low-confidence atoms dropped by the distillation threshold.
• If the site is geo-blocked and PROXY_URL is set, the fetch goes through the proxy; otherwise a research-level snippet fallback is used.

---

Example 6 — Verifying a fact

User: "Is it true that Memgraph is faster than Neo4j?"

memory_verify(atom_id = 113, self_critique = true)

Result:

{"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)."}

Verdicts: new · duplicate (→ stale) · corroborates (→ verified) · contradicts (→ contested).

---

Example 7 — Code analysis

User: "What functions does this module call, and who depends on it?"

memory_code_graph(language = "python", source = "<file contents>",
                  repo = "pegas-memory", path = "db.py")

Result:

{"symbols_stored": 7, "dependencies_stored": 27}

Then:

memory_search_code("upsert")

Result:

{"symbols": [
  {"repo": "pegas-memory", "path": "db.py", "symbol_name": "upsert_atom",
   "kind": "function", "line_start": 34}
]}

Inference (edges imports → depends_on, transitive):

memory_infer(if = "imports", then = "depends_on")
memory_infer(if = ["depends_on", "depends_on"], then = "depends_on")

---

Example 8 — Inspecting the graph

memory_query_graph(kind = "depends_on", top_k = 10)

Result:

{"kind": "depends_on",
 "edges": [
   {"src": "db", "dst": "psycopg", "kind": "depends_on", "inferred": true},
   {"src": "embedding", "dst": "httpx", "kind": "depends_on", "inferred": true}
 ],
 "nodes": 176, "code_symbols": 162}

---

Anti-patterns (do not do this)

Anti-pattern	Why it is wrong	Do instead
web_search to learn what your base contains	it searches the internet, not memory	memory_stats / memory_search
read on a directory	read expects a file	bash ls or the fs-search tool
memory_store of a whole article	violates the atomic-atom rule	memory_ingest
Skipping memory_search before research	re-researches known facts	check first
Reporting unverified atoms as facts	they are candidate	run memory_verify
Estimating counts	memory_stats gives exact numbers	call it