swampcastle 4.0.0

Give your AI a memory — the fourth one stayed up. No API key required.

SwampCastle

Built on the ruins of MemPalace.

The fourth one stayed up.

Local, searchable memory for AI assistants.

---

⚠ Important: Fake SwampCastle websites are distributing malware. Only trust GitHub and PyPI. See NOTICES.md.

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

1. Inspect a project

swampcastle build ~/projects/myapp

build/init previews detected rooms and entity candidates. It does not populate storage by itself.

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

4. Inspect the castle

swampcastle survey

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:

• build / init
• 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
Searching	CLI and Python search flows
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
Notices	Security notes and release errata

License

MIT — see LICENSE.