57 lines
2 KiB
Markdown
57 lines
2 KiB
Markdown
|
# Marchwarden — Project Context
|
||
|
|
|
||
|
|
## What This Is
|
||
|
|
A network of agentic research specialists (MCP servers) coordinated by a
|
||
|
|
principal investigator (PI) agent. Educational project learning agents, MCP,
|
||
|
|
and agent composition.
|
||
|
|
|
||
|
|
## Current Project State
|
||
|
|
|
||
|
|
| | |
|
||
|
|
|---|---|
|
||
|
|
| **Phase** | Phase 1 complete, Phase 2 next |
|
||
|
|
| **Last worked on** | 2026-04-08 |
|
||
|
|
| **Last commit** | `7088f45` — Merge PR #7: M1.4 MCP server |
|
||
|
|
| **Branch** | `main` (clean) |
|
||
|
|
| **Tests** | 81 passing |
|
||
|
|
| **Blocking issues** | None |
|
||
|
|
|
||
|
|
## Key Files
|
||
|
|
|
||
|
|
| File | Purpose |
|
||
|
|
|---|---|
|
||
|
|
| `researchers/web/models.py` | Research Contract v1 Pydantic models (9 types) |
|
||
|
|
| `researchers/web/tools.py` | Tavily search + URL fetch with content hashing |
|
||
|
|
| `researchers/web/trace.py` | JSONL trace logger |
|
||
|
|
| `researchers/web/agent.py` | WebResearcher — inner agentic loop |
|
||
|
|
| `researchers/web/server.py` | FastMCP server wrapping the researcher |
|
||
|
|
| `cli/main.py` | CLI shim (not yet implemented) |
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
- **Researcher** = MCP server exposing `research(question) -> ResearchResult`
|
||
|
|
- **ResearchResult** = answer + citations (with raw_excerpt) + categorized gaps +
|
||
|
|
discovery_events + open_questions + confidence + confidence_factors + cost_metadata + trace_id
|
||
|
|
- **Agent loop** = Claude tool-use loop (plan→search→fetch→iterate) + synthesis step
|
||
|
|
- **Trace** = JSONL audit log per research call at `~/.marchwarden/traces/`
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
- API keys live in `~/secrets` (not `.env`)
|
||
|
|
- Wiki is at `docs/wiki/` (local git clone, not MCP — wiki MCP is buggy)
|
||
|
|
- All merges via Forgejo API (claude-code user can't merge via MCP)
|
||
|
|
- One branch per concern, merge via PR, delete branch after
|
||
|
|
|
||
|
|
## Session Log
|
||
|
|
|
||
|
|
| Session | Date | Summary |
|
||
|
|
|---|---|---|
|
||
|
|
| 1 | 2026-04-08 | Project creation, naming, contract design, Phase 0 + Phase 1 complete (81 tests) |
|
||
|
|
|
||
|
|
## What's Next
|
||
|
|
|
||
|
|
**Phase 2: CLI Shim**
|
||
|
|
1. M2.1 — `marchwarden ask "question"` command (Click CLI, pretty-print)
|
||
|
|
2. M2.2 — `marchwarden replay <trace_id>` command
|
||
|
|
3. M2.3 — First smoke test: "What are ideal crops for a garden in Utah?"
|