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:**

```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 |