Add agent instructions, architecture doc and usage examples (English)

EXAMPLES.md

@@ -0,0 +1,231 @@
+# 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:**
+
+```json
+{"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:**
+
+```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}
+ ]}
+```
+
+**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:**
+
+```json
+{"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:**
+
+```json
+{"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:**
+
+```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)."}
+```
+
+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:**
+
+```json
+{"symbols_stored": 7, "dependencies_stored": 27}
+```
+
+Then:
+
+```
+memory_search_code("upsert")
+```
+
+**Result:**
+
+```json
+{"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:**
+
+```json
+{"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 |