foundation-plugin

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 gives your AI assistant persistent memory, deep codebase understanding, and automatic session lifecycle management. It is not an MCP server that dumps hundreds of tool definitions into your context window. It is a plugin -- hooks fire on lifecycle events at zero token cost, skills load instructions only when you invoke them, and only 7 essential MCP tools are registered.

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 -- the orchestrator (Foundation v2, retired in v3). Named after Hari Seldon, the mathematician who created psychohistory. Seldon was the multi-agent orchestration system in Foundation v2. In v3, it was retired -- Claude Code's native Task tool and parallel agent capabilities handle this natively. The multi-provider routing remains available through the /foundation:providers skill.
• 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

Tool	Context Cost	What It Does
demerzel_search	FREE	Regex pattern search across the snapshot. Optionally filter by glob pattern.
demerzel_find_symbol	FREE	Find the file where a symbol (function, class, type, variable) is exported.
demerzel_find_importers	FREE	Find all files that import a given module.
demerzel_execute	Truncated	Run shell, JavaScript, or Python in a subprocess sandbox. Output smart-truncated to 10KB.
demerzel_fetch	Truncated	Fetch URLs with HTML-to-text stripping, JSON pretty-printing, and smart truncation (20KB limit).
/foundation:snapshot	~500 tokens	Generate a new codebase snapshot with import/export graphs and symbol index.