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: UseCortex MCP Server

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.

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.

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).

Tests

pip install -e .
python -m tests.run_tests

Three 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

Dig deeper

• docs/DESIGN.md — design background: why OKF, why MCP, comparison with mem0/letta/graphiti

• docs/ROADMAP.md — progress + design decisions D1-D8 + historical pitfalls H1-H12

• WORKFLOW.md — CLI-agnostic workflow (wake/recall/distill/skill dispatch)

• SETUP.md — machine-readable adaptation intent for the CLI's AI

License

Released under the MIT License © 2026 sillogic.