Sill-Ensoul

English | 简体中文

Long-term memory that follows your agents across CLIs, projects, and sessions.

Give your CLI agents experience that doesn't vanish when you switch projects, switch tools, or start a new session — it doesn't touch your workflow, just adds memory to the agents you already use.

ensoul /ɪnˈsoʊl/ — verb. To give a CLI agent memory that carries across sessions, so it's more than a blank slate each time. An agent that's been ensouled is called an ensouler.

What it does

• Cross-CLI: one memory, shared across Claude Code / Codex / zcode / Cursor / OpenCode. Use Claude today, switch to Codex tomorrow — your agents' memory follows.

• Cross-project: memory lives in a global KB, not bound to any project repo. The bug your algo agent hit in project A is recalled in project B.

• Cross-session: every new conversation, the agent wiki_searches its own past experience first and starts with memory, not from scratch.

• Agent isolation: spin up multiple ensoulers (algorithm engineer, backend, testing, UI...) — each has its own memory bundle, no cross-contamination. Wake one, work with its experience.

• Memory is files: plain markdown (following OKF) — git-able, diff-able, editable in Obsidian. Vector stores are just an index; md is always source of truth.

• Zero external deps: SQLite FTS5 full-text search (CJK char segmentation + BM25) — no OpenAI key, no Docker, no cloud service. Model-vendor-agnostic: inference always stays in your CLI.

• Proactive distillation: when an agent hits a non-trivial pitfall or makes a reusable decision, it distills and writes it directly, then tells you what it wrote (concept_id + one-line gist). You don't have to remember to write things down, and you keep after-the-fact veto (ask it to delete/edit).

Related MCP server: mcp-chest-memory

Quick Start

After cloning, do one of these in your CLI (Claude Code / Codex / zcode / OpenCode, etc.):

# Option A: let the CLI's AI set it up (recommended — you send one message)
say: set up sill-ensoul from <repo>/SETUP.md

# Option B: more direct — paste SETUP.md contents into the chat, hit enter

The CLI's AI follows SETUP.md: installs the package → builds the KB → creates the default agent alter-ego → registers the MCP server → installs the shell. Restart the CLI, then say:

wake up alter-ego      # or 唤醒 alter-ego / 唤醒分身

alter-ego is your digital twin (default agent, empty memory). Accumulate experience with it first; once a domain (algorithm/backend/ ...) has enough, tell the CLI "create an agent called algo-engineer" for a specialized role.

默认形态 = 本地单机（上面 Quick Start）：一台电脑本地直连，零服务、零 token、记忆在本机。远程（多人/多机共享一份记忆）是扩展形态——需要部署服务器 + 客户端接入，用下面的场景表选文件。

Choose your deployment

不确定？最简单的问题：你手上有服务器地址+token 吗？ 有 → 场景 3/4；没有且只想自己用 → 场景 1（Quick Start）；想给同事用 → 场景 2。

pip install -e <repo>          # or, once published: pip install sill-ensoul
sill-ensoul-init               # builds the global KB + default agent alter-ego
# then have the CLI's AI read SETUP.md to finish MCP registration + shell install

Requires Python >= 3.10.

Global KB, not inside any project repo (private memory never enters git):

Set ENSOUL_KB=<path> to put it anywhere (e.g. a Dropbox / iCloud folder for multi-device sync). Open that folder in Obsidian — each agent is a subfolder, the .md files inside are the memory.

After install, sill-ensoul-init provides a few maintenance commands:

Supported CLI instruction files are detected automatically; only the ones that exist and already contain sill-ensoul markers are updated.

Upgrade

Upgrading an existing install is two parts, three commands — and your KB is never touched (upgrades update the package code and re-sync the shell rules only; your agents' memory stays put):

sill-ensoul-init --version                                   # what's installed now
pip install -U "git+https://github.com/sillogic/sill-ensoul.git"   # or: git pull && pip install -e <repo>
sill-ensoul-init --sync-shell                                # refresh shell rules in CLI instruction files

Restart your CLI. The full machine-readable intent for the CLI's AI (route detection, verification, what-not-to-do) is UPGRADE.md — say "upgrade sill-ensoul from <repo>/UPGRADE.md" and the CLI handles it.

How it works

  Claude Code / Codex / zcode / Cursor   ← inference runs in each CLI's model vendor, not locked
           |  load persona + wiki slice (thin shell: AGENTS.md / CLAUDE.md)
        sill-ensoul-mcp (MCP server, 8 tools, read/write/search)
           |  read/write
  knowledge/agents/<id>/   ← one OKF bundle per ensouler (markdown files)
  knowledge/agents/<id>/.fts/index.db   ← local SQLite FTS5 index, derived from the .md files

Three-layer separation (design decisions D1/D2, see docs/ROADMAP.md):

• Engine (ensoul/) — CLI-agnostic, handles data/tools only, no inference. server.py is a thin MCP shell, pass-through only.

• Shell (AGENTS.md / CLAUDE.md) — one per CLI, defines "when to wake/search/distill", references the shared WORKFLOW.md.

• Memory (knowledge/agents/<id>/) — OKF markdown files, git-able, diff-able, human-readable.

About the .fts/index.db file: Each agent bundle has a local SQLite FTS5 index that caches metadata and accelerates search. It is derived data — the .md files are always the source of truth. You can delete .fts/ at any time; it will be rebuilt on demand. SQLite is part of Python's standard library, so there is no extra install and no separate database process.

Core loop: wake (load persona + knowledge map) → recall (search relevant experience) → cite (reference real memory with concept_id) → distill (new experience, written directly with a heads-up). Memory persists across projects and sessions.

8 Tools

Multi-ensouler collaboration needs no dedicated tools: any agent can use wiki_write_concept(agent_id=...) to operate on another agent's memory — orchestrator reads/writes directly (see docs/ROADMAP.md D6).

Remote deployment (HTTP server)

Run the same 8 tools as a Streamable HTTP MCP server on any machine (VPS / home server / tailnet) so multiple machines share one knowledge base. Every request is gated by a static Bearer token (SIL-7 / D11) — single-tenant today, with an identity→KB-root seam for future multi-tenancy.

pip install "sill-ensoul[http] @ git+https://github.com/sillogic/sill-ensoul.git"   # not on PyPI yet
# or clone then: pip install ".[http]"  (quote the bracket — `.[http]` unquoted is not valid bash)
ENSOUL_MCP_TOKEN=$(openssl rand -hex 32)   # or: python -c "import secrets;print(secrets.token_hex(32))"
ENSOUL_MCP_TOKEN=... sill-ensoul-http      # default bind 0.0.0.0:8930

Dependency pin: the package requires mcp>=1.2,<2 — mcp 2.x renamed FastMCP to MCPServer and removed the mcp.server.fastmcp module, which breaks both sill-ensoul-mcp and sill-ensoul-http at startup. The upper bound is baked into pyproject.toml, so a fresh install resolves mcp 1.x automatically (migration to mcp 2.x is tracked in D11).

• Fail-closed: the server refuses to start without ENSOUL_MCP_TOKEN — an unauthenticated remote server is exactly what this is for.

• Optional: ENSOUL_MCP_HOST / ENSOUL_MCP_PORT env overrides (or --host / --port). The KB root is still ENSOUL_KB / the platform default.

Environment variables — a ready template lives in .env.example (token / KB root / host / port). For systemd, copy it to a root-only file and load it with EnvironmentFile; a ready-to-edit unit is at deploy/sill-ensoul-http.service:

sudo mkdir -p /etc/sill-ensoul
sudo cp .env.example /etc/sill-ensoul/env && sudo chmod 600 /etc/sill-ensoul/env
sudo vi /etc/sill-ensoul/env                  # 填 ENSOUL_MCP_TOKEN / ENSOUL_KB
sudo cp deploy/sill-ensoul-http.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sill-ensoul-http
systemctl status sill-ensoul-http             # 改完 env 要 restart 才生效

Migrate the KB — memory is plain files under the local KB root (knowledge/); copy the whole tree to the server's ENSOUL_KB (exclude per-agent .fts/ caches — they rebuild automatically):

# local (Windows PowerShell, in %LOCALAPPDATA%\ensoul):
tar -cf knowledge.tar --exclude=.fts knowledge
scp knowledge.tar root@<server>:/opt/sill-ensoul/
# server:
cd /opt/sill-ensoul && tar -xf knowledge.tar && ls knowledge/agents/

If multiple machines each have a KB, pick ONE as baseline first — do not blindly overwrite; merge the stragglers' unique content by hand.

Point a CLI's MCP config at it (streamable-http clients send the header on every request):

{ "type": "streamable-http", "url": "http://<server>:8930/mcp",
  "headers": { "Authorization": "Bearer <token>",
                "X-Machine-Id": "<your-hostname>" } }

or via a stdio↔HTTP bridge (works for any CLI): npx mcp-remote http://<server>:8930/mcp --allow-http --transport http-only --header "Authorization: Bearer <token>" --header "X-Machine-Id: <your-hostname>". --allow-http is required because mcp-remote refuses plain-HTTP URLs by default; --transport http-only avoids mcp-remote's SSE-fallback probe (its default http-first strategy), which conflicts with FastMCP's streamable-HTTP session handling and fails every call with 400 Bad Request: Missing session ID. The X-Machine-Id header is the machine identity (SIL-9): the server stamps it into every concept's frontmatter machine: field, so readers of a shared remote KB can tell "which machine wrote this" from "which machine am I on".

Security notes: the token is the auth boundary — never commit it; prefer a private network (Tailscale / VPN / firewall) for transport security; the stdio server (sill-ensoul-mcp) stays local-only and needs no token. On a public network, front the server with TLS (Caddy/nginx reverse proxy) so the token is not sent in clear text.

Full runbook: step-by-step deployment, restart / upgrade / KB-migration / troubleshooting lives in docs/deployment.md. Client install (remote): to point a CLI at the remote server without hand-editing configs, paste the single prompt file deploy/cli-setup/cli-remote.md into that CLI — it identifies which CLI it is, applies the matching section, and registers the remote MCP endpoint itself (see docs/deployment.md §4). Not sure which file fits you? See Choose your deployment above — pick your scenario (local / self-hosted / join existing server / switch local→remote), it tells you the file order.

Tests

pip install -e .
python -m tests.run_tests

Four release tests, all green = core loop works (each builds its own temp KB, runs straight after clone):

Status

• ✅ Core loop works: wake → recall → cite → distill → cross-project retention

• ✅ Installable: pip install + sill-ensoul-init self-boots CLI setup

• ✅ Cross-CLI verified: zcode + Claude Code both adapted

• ✅ Design final: auto-distill + notify-after (not pre-write confirmation, not full-auto). Multi-agent collaboration via orchestrator model (D6).

• See docs/ROADMAP.md

Documentation map（文件地图：谁读、管什么）

License

Released under the MIT License © 2026 sillogic.