# Foundation

> Codebase intelligence + persistent memory for Claude Code, as a single MCP server.
> **v4.0 — Seldon (multi-agent orchestration) was removed.** Its two provider-health tools were rehomed as `provider_list` / `provider_test`. See [Deprecations](#deprecations).

Foundation is an MCP server for [Claude Code](https://claude.com/claude-code) that gives an agent things the base tools don't:

- **Demerzel** — *codebase intelligence*. A compressed snapshot with an import/export graph, symbol index, complexity scores, test-coverage map, and recent-changes — so the agent can answer "who imports this?", "where is X exported?", "what does this file depend on?" without re-reading the tree. Mostly zero-cost (local file I/O + SQLite FTS5).
- **Gaia** — *persistent, searchable memory*. A local SQLite + FTS5 store with cross-session full-text search, a **temporal link graph** (`as_of` "what was true at time X"), autonomous pattern detection, and Claude Code transcript ingestion. No cloud, no embeddings API, no per-call cost.
- **Provider** — *a shared LLM provider registry* (the same one `demerzel_analyze` routes through), with two tools to list and health-check configured providers.

29 tools across the three modules. Gaia and most of Demerzel run locally and offline; only `demerzel_analyze` and `provider_test` reach out to a configured LLM provider.

---

## Install

```bash
npm install -g @sashabogi/foundation
foundation setup          # interactive: pick providers (for demerzel_analyze), paths
foundation mcp install    # register the MCP server with Claude Code
foundation hooks install  # optional: SessionStart checkpoint injection
```

Then in a project:

```bash
foundation snapshot       # build .foundation/snapshot.txt for Demerzel
```

Tools are exposed to Claude Code under the `mcp__…__demerzel_*`, `mcp__…__gaia_*`, and `mcp__…__provider_*` prefixes and are **deferred** (loaded on demand via ToolSearch) so they cost no context until used.

---

## Demerzel — codebase intelligence (9 tools)

Recommended flow before reading more than ~3 files: `demerzel_snapshot` → `demerzel_search` (free) → `demerzel_analyze` only if you need reasoning → read the specific files it points to.

| Tool | Cost | Purpose |
|------|------|---------|
| `demerzel_snapshot` | local | Build/refresh the compressed codebase snapshot |
| `demerzel_search` | free | Regex search across the snapshot |
| `demerzel_find_files` | free | Glob the file tree |
| `demerzel_find_symbol` | free | Where is a symbol exported? |
| `demerzel_find_importers` | free | What imports this file? |
| `demerzel_get_deps` | free | What does this file import? |
| `demerzel_get_context` | free | Lines of code around a location |
| `demerzel_analyze` | LLM | Multi-step analysis (RLM). Uses your configured provider; defaults to local **Ollama** (free) |
| `demerzel_semantic_search` | local | SQLite FTS5 search over the symbol index |

The snapshot is stored compressed (`.foundation/snapshot.txt.zst`). `graph` and `index` modes produce ~20% / ~5% of the full size for dependency-only work.

## Gaia — persistent memory (18 tools)

SQLite + FTS5 at `~/.foundation/gaia-memory.db`. BM25 + recency + tier + proximity + frequency scoring. No embeddings, no cloud.

**Memory:** `gaia_save`, `gaia_search`, `gaia_get`, `gaia_delete`, `gaia_stats`
**Link graph (temporal):** `gaia_link`, `gaia_invalidate`, `gaia_graph` — typed links (`depends_on`/`extends`/`reverts`/`related`/`contradicts`) with `valid_from`/`invalidated_at`, so `gaia_graph --as_of <t>` answers "what was true then?"
**Sessions:** `gaia_checkpoint`, `gaia_status`, `gaia_query`, `gaia_get_decisions`, `gaia_get_progress`, `gaia_get_changes`, `gaia_handoff`
**Autonomy:** `gaia_observe` (detect repeated decisions, blockers, hot files, knowledge gaps), `gaia_ingest_transcripts` (index `~/.claude/projects/**/*.jsonl`, incremental + deduped), `gaia_migrate`

> **Relationship to Claude Code's built-in memory:** Gaia is a *separate, searchable* store. Claude Code's `MEMORY.md` + topic files are the day-to-day notebook; Gaia is for cross-session full-text search at scale and structured link graphs that the flat notebook can't do. For routine writes, prefer built-in memory; reach for Gaia when you need search/links/checkpoints. `gaia_status` and `gaia_handoff` are superseded by Claude Code's native `/recap` and `/team-onboarding`.

## Provider — LLM provider registry (2 tools)

The provider registry that powers `demerzel_analyze` (multi-provider routing across Ollama / OpenAI / DeepSeek / Kimi / GLM / Gemini / OpenRouter / etc.) is inspectable through two tools:

| Tool | Purpose |
|------|---------|
| `provider_list` | List configured providers and their health status |
| `provider_test` | Test connectivity to a specific provider |

These were formerly `seldon_providers_list` / `seldon_providers_test`; they were rehomed out of the removed Seldon module (see below). Configure providers with `foundation setup` or `foundation provider add`.

## CLI

`foundation setup | init | start | status` · `foundation snapshot [path]` · `foundation mcp install|config` · `foundation hooks install` · `foundation provider add|test|list` · `foundation ui` (local dashboard at :3333) · `foundation vault init|sync` (optional one-way export of Gaia memories to an Obsidian vault).

---

## Deprecations

### Seldon (multi-agent orchestration) — removed in v4.0

The Seldon module and its 12 `seldon_*` tools were **deleted** (`src/tools/seldon/` is gone). The two useful, working tools — provider list/health — were rehomed as `provider_list` / `provider_test` (above). Reasons:

- **5 of 12 tools were never finished** — `seldon_plan`, `seldon_phase_create`, `seldon_verify`, `seldon_fix`, and `seldon_execute_verified` had unimplemented output parsing, in-memory-only state, and a "verification loop" that *simulated* execution and string-matched the model's prose for `"passed: yes"` (it never ran tests or applied fixes).
- **The remaining orchestration tools were thin single-call wrappers** (`seldon_invoke`/`compare`/`critique`/`review`) — a role prompt around one LLM call — and there was no real orchestrator (tools ran serially).
- **Claude Code and the surrounding toolchain now do this better, natively:**
  - Orchestration → the built-in **`Workflow`** tool (deterministic `pipeline()`/`parallel()` over subagents) and the **`Agent`** tool (concurrent subagents, fork-self, agent teams).
  - Multi-provider execution / cost routing → an external **`llm`** harness (OpenAI-compatible router across DeepSeek / Kimi / GLM / Gemini / OpenRouter, with a cost ledger).
  - Idea generation / critique → a **`diverge`** skill (isolated multi-frame ideation + critic).
  - Verified execution → a **`verify`** tool + **`adversarial-verifier`** agent (real build/test exit codes + cheap-LLM judgment) — a working replacement for `seldon_execute_verified`.

The provider *registry* itself (`src/providers/*`, `ProviderService`) stays — it powers `demerzel_analyze` and the `provider_*` tools. Only the orchestration layer is gone. This is a breaking change (tools removed), hence the **4.0.0** major bump. To restore Seldon, recover `src/tools/seldon/` from git history (last present at the `v3.1.0` tag) and re-add its registration in `src/index.ts`.

### Open Brain (pgvector semantic memory) — not implemented

Earlier docs described an optional pgvector/Supabase "Open Brain" semantic layer (`OPEN_BRAIN_URL` / `OPEN_BRAIN_KEY`). **It is not implemented in this codebase** — Gaia search is FTS5 keyword-only. Those environment variables currently do nothing; ignore them until/unless the layer ships.

---

## License

MIT © sashabogi