foundation

Foundation Plugin

"The future is not set, but it can be guided." -- Hari Seldon

Codebase intelligence and semantic memory for Claude Code, inspired by Asimov's Foundation universe.

---

What is Foundation?

Foundation is a Claude Code plugin that wraps the @sashabogi/foundation npm package and gives your AI assistant persistent memory, deep codebase understanding, and automatic session lifecycle management. The plugin itself is a thin shell: it contributes hooks that fire on lifecycle events at zero token cost, skills that load instructions only when you invoke them, a local UI server, and a stable adapter to the bundled MCP server. The MCP server (shipped by the npm package) registers 29 tools spanning Demerzel (codebase intelligence), Gaia (local memory), and a small provider registry (provider_list / provider_test). In Claude Code 2.1+ those tools are loaded on demand via the deferred-tool system, so they cost no context until you call them.

The naming comes from Isaac Asimov's Foundation series. In the novels, Hari Seldon created the Foundation to preserve human knowledge through the collapse of the Galactic Empire -- a millennia-long dark age where everything would otherwise be forgotten. This plugin does the same thing for your development work: it preserves architectural decisions, codebase understanding, and project context across sessions, projects, and tools, so nothing is lost when a conversation ends or a context window resets.

Three core systems power the plugin:

• Demerzel -- the codebase watcher. Named after R. Daneel Olivaw (who also went by Eto Demerzel), the 20,000-year-old robot who quietly guided humanity from the shadows. Demerzel builds structural snapshots of your codebase -- import graphs, export maps, symbol indexes -- so Claude can answer architecture questions without reading every file.
• Gaia -- the local memory. Named after the planet with collective consciousness, where every organism shared a single mind. Gaia is a local SQLite + FTS5 database that connects sessions, projects, and insights through a unified knowledge graph with typed relationships.
• Seldon -- documentation architecture. Named after Hari Seldon, who founded the Foundation to compile the Encyclopedia Galactica and preserve civilization's knowledge against forgetting. Seldon keeps a project's documentation legible as it grows: three skills (/foundation:doc-inventory, /foundation:doc-restructure, /foundation:doc-portal) plus a SessionStart hook that auto-loads the nearest AGENTS.md context tree. (Seldon was previously Foundation's multi-agent orchestrator; that role has been sunsetted -- orchestration now lives in Scrooge and Claude Code's native agents -- and the name was repurposed for the documentation pillar.) See the Seldon section below for details.
• Open Brain -- the cloud semantic memory. Built on the OB1 (Open Brain) architecture by Nate Jones, this optional layer adds pgvector-powered semantic search via Supabase, so you can find memories by meaning, not just keywords.

---

Quick Install

# Add the marketplace
claude plugin marketplace add sashabogi/foundation-plugin

# Install the plugin
claude plugin install foundation

# Restart Claude Code

That's it. No environment variables required for core functionality. Open Brain cloud memory is optional (see setup below).

---

Core Systems

Demerzel -- Codebase Intelligence

"I have been watching for 20,000 years."

Demerzel creates a structural understanding of your codebase without requiring Claude to read every file. When you generate a snapshot (via /foundation:snapshot), Demerzel walks your project tree, parses imports and exports, builds a symbol index, maps the dependency graph, and writes a compact representation to .foundation/snapshot.txt.

From that snapshot, Claude can:

• Search by regex across the entire codebase without reading files
• Find where any symbol is exported -- functions, classes, types, variables
• Trace the import graph -- who imports what, and what does each file depend on
• Understand architecture through AI-powered analysis using the Recursive Language Model (RLM) engine

The snapshot captures: file paths, line counts, import/export relationships, symbol locations, and the full dependency graph (both import graph and reverse export graph). Search operations against the snapshot are free -- they cost zero tokens beyond the results themselves.

Demerzel Tools