# CogniRepo — Memory & Code Intelligence for {project_name}

> **Auto-generated by `cognirepo init`.**
> Project path: `{project_path}`
> All data is scoped to `.cognirepo/` in this project — never shared across projects.

## What is CogniRepo?

CogniRepo is the **local cognitive infrastructure layer** wired into this project.
It gives you semantic memory, AST code indexing, a knowledge graph, and episodic history — all
accessible via MCP tools without consuming tokens for repeated context retrieval.

## TOOL-FIRST WORKFLOW (MANDATORY)

Do NOT read raw files, grep, or assume code location before calling CogniRepo tools.
Every session starts with tools — not file reads, not assumptions, not skipping search.

### MANDATORY before any file access:
1. `context_pack(query)` — BEFORE reading any file >100 lines
2. `lookup_symbol(name)` — BEFORE grepping for a function
3. `who_calls(fn_name)` — BEFORE grepping for callers
4. `subgraph(entity)` — BEFORE answering architecture questions

### NEVER:
- NEVER use read_file or raw grep before calling `context_pack` first
- NEVER assume where a function lives — call `lookup_symbol` first
- NEVER skip semantic search for bugs — call `retrieve_memory` before assuming

## CogniRepo Tool Routing (follow strictly)

| When | Action |
|------|--------|
| BEFORE reading any file >100 lines | call `context_pack(query)` first |
| BEFORE grepping for a function | call `lookup_symbol(name)` first |
| BEFORE grepping for callers | call `who_calls(fn_name)` first — if empty → then grep |
| BEFORE asking about architecture | call `retrieve_learnings("architecture overview")` |
| AFTER every non-trivial decision | run `store_memory("decision: [what and why]")` |
| AFTER finding a bug or quirk | run `store_memory("quirk: [what and where]")` |
| NEVER read multiple files manually | when `context_pack` covers the query |

**Fallback rules:**
- If `context_pack` returns `status: "no_confident_match"` → fall back to grep/Read
- If `who_calls` returns `found_via: "dynamic_dispatch_fallback"` → treat as medium confidence, verify with one Read call

## MCP Tools Available

### Core retrieval
| Tool | Description | When to use |
|------|-------------|-------------|
| `context_pack(query)` | Token-efficient code context (code-first, no README noise) | FIRST call before any file read |
| `lookup_symbol(name)` | O(1) symbol lookup — file + line | Before reading code |
| `who_calls(function_name)` | Trace callers + dynamic dispatch fallback | Impact analysis, refactoring |
| `retrieve_memory(query, top_k=5)` | Semantic similarity search over stored memories | Before answering — pull past context |
| `search_docs(query)` | Full-text search in all `.md` files with snippets | Documentation lookups |
| `subgraph(entity, depth=1)` | Local knowledge graph neighbourhood | Understand relationships |
| `graph_stats()` | Node/edge count and graph health | Check if graph has data |
| `episodic_search(query, limit=10)` | Keyword search in event history | Find past decisions |

### User & session intelligence
| Tool | Description | When to use |
|------|-------------|-------------|
| `get_user_profile()` | User's interaction style: depth pref, vocabulary, question types | **Call at session start** to calibrate response style |
| `get_session_history(limit=10)` | Recent conversation exchanges across sessions | Resuming context from prior sessions |

### Error tracking & prevention
| Tool | Description | When to use |
|------|-------------|-------------|
| `get_error_patterns()` | Recurring errors with prevention hints | Before proposing a fix — check if it has failed before |
| `record_error(error_type, message, file_path, query_context)` | Log an error for future avoidance | After any error Claude or user encounters |

### Memory & storage
| Tool | Description | When to use |
|------|-------------|-------------|
| `store_memory(text, source="")` | Persist a memory to the FAISS index | After solving bugs, recording decisions |
| `log_episode(event, metadata={})` | Record a significant event to episodic log | Track important milestones |

## Recommended Workflow

### On session start
1. `get_user_profile()` → calibrate response depth and terminology
2. `get_error_patterns()` → know what has failed before in this repo

### On Complex Code Questions
1. `context_pack("{question}")` → packed code + memory context, called **before** any file read
2. `retrieve_memory("{question keyword}")` → pull relevant past context
3. `lookup_symbol("ClassName or function_name")` → find source location
4. Answer based on combined context

### After Solving a Bug
```
store_memory("Fixed: {bug summary} — root cause was X, fix was Y", source="debug")
```

### After Encountering an Error
```
record_error("TypeError", "expected str got int in parse_config", "config/parser.py", "{query that led here}")
```

### Navigating Unfamiliar Code
1. `graph_stats()` → confirm graph has data (run `cognirepo index-repo .` if not)
2. `who_calls("function_name")` → understand callers
3. `subgraph("module_name", depth=2)` → explore relationships

## Project Storage Layout

```
.cognirepo/
  config.json         ← project settings
  vector_db/          ← FAISS semantic memory (project-scoped)
  graph/              ← knowledge graph (project-scoped)
  index/              ← AST symbol index (project-scoped)
  episodic/           ← event log (project-scoped)
  sessions/           ← conversation history
  errors/             ← error logs (date-stamped)
```

**Important:** This project's CogniRepo data is completely isolated from other projects.
Never call tools expecting cross-project context.

## Keeping Memory Fresh

- Index this repo periodically: `cognirepo index-repo .`
- Prune stale memories: `cognirepo prune`
- Check health: `cognirepo doctor`
- Seed from git history: `cognirepo seed --from-git`
- Session bootstrap: `cognirepo prime`
