swampcastle 4.0.0__tar.gz

swampcastle-4.0.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "swampcastle",
+  "interface": {
+    "displayName": "SwampCastle"
+  },
+  "plugins": [
+    {
+      "name": "swampcastle",
+      "source": {
+        "source": "local",
+        "path": "./.codex-plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "NONE"
+      },
+      "category": "Coding"
+    }
+  ]
+}

swampcastle-4.0.0/.claude-plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "swampcastle": {
+    "command": "python3",
+    "args": [
+      "-m",
+      "swampcastle.drawbridge"
+    ]
+  }
+}

swampcastle-4.0.0/.claude-plugin/README.md

@@ -0,0 +1,57 @@
+# SwampCastle Claude Code Plugin
+
+A Claude Code plugin that gives your AI a persistent memory system. Mine projects and conversations into a searchable palace backed by ChromaDB, with 19 MCP tools, auto-save hooks, and 5 guided skills.
+
+## Prerequisites
+
+- Python 3.9+
+
+## Installation
+
+### Claude Code Marketplace
+
+```bash
+claude plugin marketplace add dekoza/swampcastle
+claude plugin install --scope user swampcastle
+```
+
+### Local Clone
+
+```bash
+claude plugin add /path/to/swampcastle
+```
+
+## Post-Install Setup
+
+After installing the plugin, run the init command to complete setup (pip install, MCP configuration, etc.):
+
+```
+/swampcastle:init
+```
+
+## Available Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/swampcastle:help` | Show available tools, skills, and architecture |
+| `/swampcastle:init` | Set up SwampCastle -- install, configure MCP, onboard |
+| `/swampcastle:search` | Search your memories across the palace |
+| `/swampcastle:mine` | Mine projects and conversations into the palace |
+| `/swampcastle:status` | Show palace overview -- wings, rooms, drawer counts |
+
+## Hooks
+
+SwampCastle registers two hooks that run automatically:
+
+- **Stop** -- Saves conversation context every 15 messages.
+- **PreCompact** -- Preserves important memories before context compaction.
+
+Set the `MEMPAL_DIR` environment variable to a directory path to automatically run `swampcastle mine` on that directory during each save trigger.
+
+## MCP Server
+
+The plugin automatically configures a local MCP server with 19 tools for storing, searching, and managing memories. No manual MCP setup is required -- `/swampcastle:init` handles everything.
+
+## Full Documentation
+
+See the main [README](../README.md) for complete documentation, architecture details, and advanced usage.

swampcastle-4.0.0/.claude-plugin/commands/help.md

@@ -0,0 +1,6 @@
+---
+description: Show comprehensive SwampCastle help — available skills, MCP tools, CLI commands, hooks, and architecture.
+allowed-tools: Bash, Read
+---
+
+Invoke the generic swampcastle skill (using the Skill tool) with the `help` command, then follow its instructions.

swampcastle-4.0.0/.claude-plugin/commands/init.md

@@ -0,0 +1,6 @@
+---
+description: Set up SwampCastle — install the package, initialize a palace, configure MCP server, and verify everything works.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+Invoke the generic swampcastle skill (using the Skill tool) with the `init` command, then follow its instructions.

swampcastle-4.0.0/.claude-plugin/commands/mine.md

@@ -0,0 +1,7 @@
+---
+description: Mine projects and conversations into the SwampCastle. Supports project files, conversation exports, and auto-classification.
+argument-hint: Path to project or conversation export to mine.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+Invoke the generic swampcastle skill (using the Skill tool) with the `mine` command, then follow its instructions.

swampcastle-4.0.0/.claude-plugin/commands/search.md

@@ -0,0 +1,7 @@
+---
+description: Search your memories across the SwampCastle using semantic search with wing/room filtering.
+argument-hint: Search query, optionally with wing/room filters.
+allowed-tools: Bash, Read
+---
+
+Invoke the generic swampcastle skill (using the Skill tool) with the `search` command, then follow its instructions.

swampcastle-4.0.0/.claude-plugin/commands/status.md

@@ -0,0 +1,6 @@
+---
+description: Show the current state of your memory palace — wings, rooms, drawer counts, and suggestions.
+allowed-tools: Bash, Read
+---
+
+Invoke the generic swampcastle skill (using the Skill tool) with the `status` command, then follow its instructions.

swampcastle-4.0.0/.claude-plugin/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "description": "MemPalace auto-save and pre-compact hooks",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/mempal-stop-hook.sh"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/mempal-precompact-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

swampcastle-4.0.0/.claude-plugin/hooks/mempal-precompact-hook.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# SwampCastle PreCompact Hook — thin wrapper calling Python CLI
+# All logic lives in swampcastle.hooks_cli for cross-harness extensibility
+INPUT=$(cat)
+echo "$INPUT" | python3 -m swampcastle hook run --hook precompact --harness claude-code

swampcastle-4.0.0/.claude-plugin/hooks/mempal-stop-hook.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# SwampCastle Stop Hook — thin wrapper calling Python CLI
+# All logic lives in swampcastle.hooks_cli for cross-harness extensibility
+INPUT=$(cat)
+echo "$INPUT" | python3 -m swampcastle hook run --hook stop --harness claude-code

swampcastle-4.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "swampcastle",
+  "owner": {
+    "name": "milla-jovovich",
+    "url": "https://github.com/milla-jovovich"
+  },
+  "plugins": [
+    {
+      "name": "swampcastle",
+      "source": "./.claude-plugin",
+      "description": "AI memory system — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, guided setup.",
+      "version": "3.0.14",
+      "author": {
+        "name": "milla-jovovich"
+      }
+    }
+  ]
+}

swampcastle-4.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "swampcastle",
+  "version": "3.0.14",
+  "description": "Give your AI a memory — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, and guided setup.",
+  "author": {
+    "name": "milla-jovovich"
+  },
+  "license": "MIT",
+  "commands": [],
+  "mcpServers": {
+    "swampcastle": {
+      "command": "python3",
+      "args": [
+        "-m",
+        "swampcastle.drawbridge"
+      ]
+    }
+  },
+  "keywords": [
+    "memory",
+    "ai",
+    "rag",
+    "mcp",
+    "chromadb",
+    "palace",
+    "search"
+  ],
+  "repository": "https://github.com/dekoza/swampcastle"
+}

swampcastle-4.0.0/.claude-plugin/skills/mempalace/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: swampcastle
+description: SwampCastle — mine projects and conversations into a searchable memory palace. Use when asked about swampcastle, memory palace, mining memories, searching memories, or palace setup.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# SwampCastle
+
+A searchable memory palace for AI — mine projects and conversations, then search them semantically.
+
+## Prerequisites
+
+Ensure `swampcastle` is installed:
+
+```bash
+swampcastle --version
+```
+
+If not installed:
+
+```bash
+pip install swampcastle
+```
+
+## Usage
+
+SwampCastle provides dynamic instructions via the CLI. To get instructions for any operation:
+
+```bash
+swampcastle instructions <command>
+```
+
+Where `<command>` is one of: `help`, `init`, `mine`, `search`, `status`.
+
+Run the appropriate instructions command, then follow the returned instructions step by step.

swampcastle-4.0.0/.codex-plugin/README.md

@@ -0,0 +1,75 @@
+# SwampCastle - Codex CLI Plugin
+
+Give your AI a persistent memory -- mine projects and conversations into a searchable palace backed by ChromaDB, with 19 MCP tools, auto-save hooks, and guided skills.
+
+## Prerequisites
+
+- Python 3.9+
+- Codex CLI installed and configured
+- `pip install swampcastle`
+
+## Installation
+
+### Local Install
+
+1. Copy or symlink the `.codex-plugin` directory into your project root:
+
+```bash
+cp -r .codex-plugin /path/to/your/project/.codex-plugin
+```
+
+2. Verify the plugin is detected:
+
+```bash
+codex --plugins
+```
+
+3. Initialize your palace:
+
+```bash
+codex /init
+```
+
+### Git Install
+
+1. Clone the SwampCastle repository:
+
+```bash
+git clone https://github.com/dekoza/swampcastle.git
+cd swampcastle
+```
+
+2. Install the Python package:
+
+```bash
+pip install -e .
+```
+
+3. The `.codex-plugin` directory is already in the repo root. Codex CLI will detect it automatically when you run Codex from inside the repository.
+
+4. Initialize your palace:
+
+```bash
+codex /init
+```
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `/help` | Show available commands and usage tips |
+| `/init` | Initialize a new memory palace |
+| `/search` | Semantic search across all mined memories |
+| `/mine` | Mine a project or conversation into your palace |
+| `/status` | Show palace status, room counts, and health |
+
+## Hooks
+
+The plugin includes auto-save hooks that run on session stop (every 15 messages) and before context compaction, automatically preserving conversation context into your palace.
+
+Set the `MEMPAL_DIR` environment variable to a directory path to automatically run `swampcastle mine` on that directory during each save trigger.
+
+## Support
+
+- Repository: https://github.com/dekoza/swampcastle
+- Issues: https://github.com/dekoza/swampcastle/issues

swampcastle-4.0.0/.codex-plugin/hooks/mempal-hook.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOK_NAME="${1:?Usage: mempal-hook.sh <hook-name>}"
+INPUT_FILE=$(mktemp) || { echo "Failed to create temp file" >&2; exit 1; }
+cat > "$INPUT_FILE"
+cat "$INPUT_FILE" | python3 -m swampcastle hook run --hook "$HOOK_NAME" --harness codex
+EXIT_CODE=$?
+rm -f "$INPUT_FILE" 2>/dev/null
+exit $EXIT_CODE

swampcastle-4.0.0/.codex-plugin/hooks.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh session-start"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh stop"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/hooks/mempal-hook.sh precompact"
+          }
+        ]
+      }
+    ]
+  }
+}

swampcastle-4.0.0/.codex-plugin/plugin.json

@@ -0,0 +1,52 @@
+{
+  "name": "swampcastle",
+  "version": "3.0.14",
+  "description": "Give your AI a memory — mine projects and conversations into a searchable palace. 19 MCP tools, auto-save hooks, and guided setup.",
+  "author": {
+    "name": "milla-jovovich"
+  },
+  "homepage": "https://github.com/dekoza/swampcastle",
+  "repository": "https://github.com/dekoza/swampcastle",
+  "license": "MIT",
+  "keywords": [
+    "memory",
+    "ai",
+    "rag",
+    "mcp",
+    "chromadb",
+    "palace",
+    "search"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": {
+    "swampcastle": {
+      "command": "python3",
+      "args": [
+        "-m",
+        "swampcastle.drawbridge"
+      ]
+    }
+  },
+  "interface": {
+    "displayName": "SwampCastle",
+    "shortDescription": "AI memory system for Codex",
+    "longDescription": "Give your AI a persistent memory — mine projects and conversations into a searchable palace backed by ChromaDB, with 19 MCP tools, auto-save hooks, and guided skills.",
+    "developerName": "milla-jovovich",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/dekoza/swampcastle",
+    "privacyPolicyURL": "https://github.com/dekoza/swampcastle",
+    "termsOfServiceURL": "https://github.com/dekoza/swampcastle",
+    "defaultPrompt": [
+      "Search my memories for recent decisions",
+      "Mine this project into my memory palace",
+      "Show my palace status and room counts"
+    ],
+    "brandColor": "#7C3AED"
+  }
+}

swampcastle-4.0.0/.codex-plugin/skills/help/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: help
+description: Show SwampCastle help — available commands, usage tips, and getting started guidance.
+allowed-tools: Bash, Read
+---
+
+# SwampCastle Help
+
+Run the following command and follow the returned instructions step by step:
+
+```bash
+swampcastle instructions help
+```

swampcastle-4.0.0/.codex-plugin/skills/init/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: init
+description: Initialize a new SwampCastle — guided setup for your AI memory palace with ChromaDB backend.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# SwampCastle Init
+
+Run the following command and follow the returned instructions step by step:
+
+```bash
+swampcastle instructions init
+```

swampcastle-4.0.0/.codex-plugin/skills/mine/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: mine
+description: Mine a project or conversation into your SwampCastle — extract and store memories for later retrieval.
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# SwampCastle Mine
+
+Run the following command and follow the returned instructions step by step:
+
+```bash
+swampcastle instructions mine
+```

swampcastle-4.0.0/.codex-plugin/skills/search/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: search
+description: Search your SwampCastle — semantic search across all mined memories, projects, and conversations.
+allowed-tools: Bash, Read
+---
+
+# SwampCastle Search
+
+Run the following command and follow the returned instructions step by step:
+
+```bash
+swampcastle instructions search
+```

swampcastle-4.0.0/.codex-plugin/skills/status/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: status
+description: Show SwampCastle status — room counts, storage usage, and palace health.
+allowed-tools: Bash, Read
+---
+
+# SwampCastle Status
+
+Run the following command and follow the returned instructions step by step:
+
+```bash
+swampcastle instructions status
+```

swampcastle-4.0.0/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.venv
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage/
+benchmarks/
+node_modules/

swampcastle-4.0.0/.github/CODEOWNERS

@@ -0,0 +1,13 @@
+# Default owners for everything
+* @milla-jovovich @bensig @igorls
+
+# Core library
+mempalace/ @milla-jovovich @bensig
+
+# CI and workflows
+.github/ @bensig
+
+# Plugins and integrations
+.claude-plugin/ @bensig
+.codex-plugin/ @bensig
+integrations/ @bensig

swampcastle-4.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug Report
+about: Something isn't working
+labels: bug
+---
+
+**What happened?**
+
+**What did you expect?**
+
+**How to reproduce:**
+
+1.
+2.
+3.
+
+**Environment:**
+- OS:
+- Python version:
+- MemPal version: (check `python mempal.py --version` or git SHA)

swampcastle-4.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest an improvement
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+**What's the proposed solution?**
+
+**Alternatives considered:**

swampcastle-4.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+## What does this PR do?
+
+## How to test
+
+## Checklist
+- [ ] Tests pass (`python -m pytest tests/ -v`)
+- [ ] No hardcoded paths
+- [ ] Linter passes (`ruff check .`)

swampcastle-4.0.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3

swampcastle-4.0.0/.github/workflows/bump-plugin-version.yml.disabled

@@ -0,0 +1,51 @@
+name: Bump Version
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Bump patch version
+        run: |
+          CURRENT=$(python3 -c "exec(open('mempalace/version.py').read()); print(__version__)")
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+          PATCH=$((PATCH + 1))
+          NEW="${MAJOR}.${MINOR}.${PATCH}"
+          echo "__version__ = \"${NEW}\"" > mempalace/version.py
+          # Prepend docstring
+          sed -i '1i"""Single source of truth for the MemPalace package version."""\n' mempalace/version.py
+          echo "version=$NEW" >> "$GITHUB_OUTPUT"
+        id: version
+
+      - name: Sync plugin.json
+        run: |
+          jq --arg v "${{ steps.version.outputs.version }}" '.version = $v' .claude-plugin/plugin.json > tmp.json && mv tmp.json .claude-plugin/plugin.json
+
+      - name: Sync marketplace.json
+        run: |
+          jq --arg v "${{ steps.version.outputs.version }}" '.plugins[0].version = $v' .claude-plugin/marketplace.json > tmp.json && mv tmp.json .claude-plugin/marketplace.json
+
+      - name: Sync codex plugin.json
+        run: |
+          jq --arg v "${{ steps.version.outputs.version }}" '.version = $v' .codex-plugin/plugin.json > tmp.json && mv tmp.json .codex-plugin/plugin.json
+
+      - name: Sync pyproject.toml
+        run: |
+          sed -i "s/^version = \".*\"/version = \"${{ steps.version.outputs.version }}\"/" pyproject.toml
+
+      - name: Commit and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add mempalace/version.py .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json pyproject.toml
+          if ! git diff --staged --quiet; then
+            git commit -m "chore: bump version to ${{ steps.version.outputs.version }}"
+            git push
+          fi