Package Exports

@sashabogi/foundation
@sashabogi/foundation/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@sashabogi/foundation) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.

Foundation is an MCP server for 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

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:

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

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.

@sashabogi/foundation