SwampCastle

Built on the foundations of MemPalace.

The fourth one stayed up.

Local, searchable memory for AI assistants.

---

What SwampCastle is

SwampCastle v4 stores verbatim memory in a collection backend and structured facts in a graph backend.

• Local mode: LanceDB + SQLite
• Server mode: PostgreSQL + pgvector
• Test mode: in-memory stores

The public architecture is:

CLI / MCP / Sync
      ↓
   Castle
      ├── CatalogService
      ├── SearchService
      ├── VaultService
      └── GraphService
      ↓
CollectionStore + GraphStore

The spatial model is still the same:

WING (project / person / domain)
  └── ROOM (topic)
        └── DRAWER (verbatim text chunk)

Install

pip install swampcastle

Requirements

• Python 3.11+
• first-run ONNX model download for the default embedder (~87 MB, cached locally)

Optional extras:

pip install 'swampcastle[server]'    # FastAPI + uvicorn for sync server
pip install 'swampcastle[postgres]'  # PostgreSQL + pgvector backend
pip install 'swampcastle[gpu]'       # sentence-transformers embedder support
pip install 'swampcastle[chroma]'    # legacy ChromaDB tooling for migration only

Quick start

Before doing anything else, SwampCastle will create a default global runtime config at ~/.swampcastle/config.json the first time you use the CLI. The default backend is Lance. If you want to change backend or storage settings, run:

swampcastle wizard

The wizard can also store your own identity in ~/.swampcastle/entity_registry.json so SwampCastle can recognize you by name or nickname during ingest.

If you stick with the canonical CPU ONNX embedder and want to rerun the local performance benchmark later, use:

swampcastle tune

1. Prepare a project

swampcastle project ~/projects/myapp --team dekoza sarah

project creates project-local mining config in .swampcastle.yaml. It does not ingest files by itself. If an older swampcastle.yaml exists, SwampCastle will migrate it to the hidden filename and tell you.

The optional team list lets ingest tag drawers with a best-effort contributor identity from git history.

2. Ingest files

swampcastle gather ~/projects/myapp

Conversation exports use the same command:

swampcastle gather ~/chat-exports --mode convos --wing myapp

3. Search

swampcastle seek "why did we switch auth providers"
swampcastle seek "pricing" --wing myapp --room billing
swampcastle seek "auth migration" --contributor dekoza

4. Inspect the castle

swampcastle survey
swampcastle brief --wing myapp

Use brief (alias: minstrel) when you want a human-readable wing summary. Use herald when you want the strict SwampCastle memory-use protocol for agent instructions.

MCP setup

Show the setup command:

swampcastle drawbridge

Run the server directly:

swampcastle drawbridge run
# or
swampcastle-mcp

Example Claude Code setup:

claude mcp add swampcastle -- swampcastle-mcp

Example Gemini CLI setup:

gemini mcp add swampcastle swampcastle-mcp --scope user

See docs/mcp.md.

Python API

Recommended entry point:

from swampcastle.castle import Castle
from swampcastle.models import AddDrawerCommand, SearchQuery
from swampcastle.settings import CastleSettings
from swampcastle.storage import factory_from_settings

settings = CastleSettings(_env_file=None)
factory = factory_from_settings(settings)

with Castle(settings, factory) as castle:
    castle.vault.add_drawer(
        AddDrawerCommand(
            wing="myapp",
            room="auth",
            content="We switched providers because rotation and local testing got simpler.",
        )
    )

    result = castle.search.search(SearchQuery(query="provider switch", wing="myapp"))
    print(result.results)

For low-level backend access, see docs/python-api.md.

Sync

Hub:

pip install 'swampcastle[server]'
swampcastle serve --host 0.0.0.0 --port 7433

Client:

swampcastle sync --server http://homeserver:7433

SwampCastle sync now works against the configured collection backend. Version vectors are still stored locally alongside castle_path.

See docs/sync.md.

Legacy Chroma migration

SwampCastle can raise a legacy ChromaDB palace into the v4 local castle layout:

swampcastle raise --source-palace ~/.mempalace/palace

By default the target is your configured castle_path (usually ~/.swampcastle/castle). You can override it:

swampcastle raise --source-palace ~/.mempalace/palace --target-castle /tmp/swampcastle/castle
swampcastle raise --source-palace ~/.mempalace/palace --dry-run

The source palace is left untouched. Drawer data is imported into LanceDB, and common sidecar files such as the knowledge graph and sync identity files are copied when present.

Current state of the CLI

The core ingest / search / MCP / sync path is working:

• project
• gather / mine
• seek / search
• survey / status
• drawbridge / mcp
• serve / sync

Some maintenance commands are still being rebuilt and are intentionally thin right now:

• reforge / reindex
• distill / compress

The docs call that out explicitly where relevant instead of pretending those flows are complete.

Documentation

Document	Contents
Getting started	First ingest, first search, MCP setup
Architecture	Castle, services, storage contracts, backends
CLI reference	Real command surface and aliases
Configuration	CastleSettings, env vars, backend selection
Mining	Project + conversation ingest
Mining adapters	Internal ingest adapter seam and declared transformations
Searching	CLI and Python search flows
Audit overlay	Source-origin manifests, local curation files, derived catalogs/traces, transcript auto-ingest, explainable search
Knowledge graph	Graph service and direct stores
MCP server	Setup and tool catalog
Sync	Hub / spoke sync model
Hooks	Hook protocol and supported harnesses
Python API	Programmatic usage
AAAK dialect	Experimental compression layer
Migration	Moving from MemPalace
Changelog	Release history and notable changes
Notices	Security notes and release errata

License

MIT — see LICENSE.