the-soul

v0.1.7

Published

9 days ago

Install-and-forget local memory for agents.

0High
0Medium
0Low

mexaar_

The Soul gives agents one local memory they can share.

They can search it, read it, and improve it through safe structured writes.

The memory itself stays plain files. The source of truth is OKF: markdown files with YAML frontmatter.

The Soul is early v0.1. Usable, but pre-1.0. APIs, adapters, and install details may still change before 1.0.

Current verified boundary:

CLI, MCP server creation, package import, TypeScript import, and npm package dry-run are covered by release gates.
Claude Stop/SessionEnd and Codex Stop hooks queue safe durable memory jobs. soul hook-job consume runs bounded local Claude/Codex subprocess adapters and commits accepted structured patches through core.
MCP remember and ingest return protocol tasks for the calling agent. They do not commit memory by themselves.
Search is deterministic local lexical retrieval with a frozen baseline. It is not semantic retrieval.
GitHub release gates use deterministic fake-runner boundaries. Local operators can run bun run certify:agents to prove current authenticated Claude/Codex CLI compatibility.

Quick Start

npm install -g the-soul
soul init
soul install claude # or codex, cursor, pi, opencode, gemini, vibe
soul doctor

Bun alternative:

bun install -g the-soul
soul init
soul install claude
soul doctor

Want your agent to do it for you? Use the copy/paste setup prompt.

Key features

🧠 Shared memory across agents — Claude, Codex, Cursor, Pi, OpenCode, Gemini, Vibe.
📁 Plain-file source of truth — OKF bundles: markdown + YAML frontmatter.
🔒 Safe writes — lock, validate, patch, atomic write, update index/log.
🔍 Local search — simple local index, no required embeddings or vector DB.
🔌 CLI + MCP + adapters — install the best supported integration per agent.
🧹 Health tools — soul doctor, soul lint, soul migrate plan.

Documentation

Protocol — Soul Memory Protocol, task kinds, structured patches, write flow.
OKF compatibility — what OKF v0.1 means and what The Soul supports.
Adapters — supported agents, install behavior, safety rules.
Release versioning — OKF-aligned package versioning.
npm hardening — package dry-run and publish checklist.

Why this exists

Agents forget.

Each tool has its own context:

Claude has one session.
Cursor has another.
Codex has another.
Gemini has another.
Local scripts have none.

So teams repeat the same facts:

project rules;
architecture decisions;
user preferences;
adapter constraints;
rejected choices;
gotchas found during debugging.

The Soul gives these agents one shared local memory.

Not chat history. Durable knowledge.

What The Soul does

The Soul installs a small TypeScript package with:

soul CLI;
MCP server;
adapter installers;
hooks where an agent supports them;
safe memory write core;
local search;
OKF read/write support;
lint and migration tools.

It is install-and-forget in spirit:

create memory once;
install support for your agent;
let agents read and improve the same memory.

How it works

Human / agent session
        |
        v
Agent integration
(CLI, MCP, hook, instruction)
        |
        v
Soul Memory Protocol
(remember, search, read, lint, migrate)
        |
        v
The Soul core
(lock -> validate -> patch -> atomic write -> index/log)
        |
        v
OKF memory bundles
~/.agents/memory/bundles/

The important rule:

Adapters do not write memory files directly.

They call The Soul. The core owns writes.

That gives every agent the same safety rules:

global lock;
latest-file read before write;
structured patch;
OKF validation;
atomic write;
index.md and log.md update;
rebuildable cache/index.

OKF, explained simply

OKF means Open Knowledge Format.

Official sources:

Google Cloud intro: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/
OKF repository: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf
OKF v0.1 spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

OKF is simple:

memory bundle/
  index.md
  log.md
  decisions/
    runtime.md
  architecture/
    core.md

Each concept is a markdown file:

---
type: Decision
title: Runtime target
tags: [runtime, node]
---

The package targets Node.js LTS.

# Citations

[1] Conversation, 2026-07-07 — runtime decision.

Why OKF is useful:

humans can read it;
agents can parse it;
git can diff it;
tools can link it;
no database required;
no vendor lock-in.

The Soul does not replace OKF. It uses OKF v0.1 as its first backend and keeps The Soul-specific state rebuildable.

More: docs/okf-compatibility.md

Install

Main path:

npm install -g the-soul
soul init
soul install claude # or codex, cursor, pi, opencode, gemini, vibe
soul doctor

Bun alternative:

bun install -g the-soul
soul init
soul install claude
soul doctor

If the npm package is not published yet, install from the repository during development:

git clone <repo-url>
cd the-soul
bun install
bun run build
bun run soul -- --help

Copy/paste setup prompt for your LLM agent

Paste this into your coding agent:

Install The Soul for this machine and connect yourself to it.

Rules:
- Ask before changing global agent config if the tool requires confirmation.
- Do not commit.
- Do not push.
- Do not edit unrelated files.
- Report every file you change.

Steps:
1. Check whether `soul` is available with `soul --version`.
2. If missing, install it with `npm install -g the-soul`.
   If this machine uses Bun globally, `bun install -g the-soul` is acceptable.
3. Run `soul init`.
4. Detect which agent environment you are running in.
   Choose one of: claude, codex, cursor, pi, opencode, gemini, vibe.
5. Run `soul install <agent>` for the detected agent.
6. Run `soul doctor`.
7. If doctor reports a fix, explain it and ask before risky changes.
8. Return a short report: install status, memory path, adapter installed, changed files, remaining warnings.

Commands

soul --help
soul --version

Core commands:

soul init
soul remember "Durable fact to remember"
soul search "query"
soul read project/decisions/runtime.md
soul lint
soul doctor
soul migrate plan

Agent / integration commands:

soul install claude
soul install codex
soul install cursor
soul install pi
soul install opencode
soul install gemini
soul install vibe
soul mcp

remember modes:

soul remember "text" --dry-run
soul remember "text" --json
soul remember --patch-file patch.json

The default remember mode is a preview. Real writes use strict structured patch payloads through the core.

Adapters

Supported now:

| Agent | Install command | |---|---| | Claude | soul install claude | | Codex | soul install codex | | Cursor | soul install cursor | | Pi | soul install pi | | OpenCode | soul install opencode | | Gemini | soul install gemini | | Vibe / Mistral | soul install vibe |

Adapters may install a mix of:

MCP config;
CLI fallback instructions;
hooks;
skills;
commands;
agent instruction files.

Exact capability depends on the agent.

More: docs/adapters.md

Memory layout

Default memory folder:

~/.agents/memory

Override:

SOUL_MEMORY_DIR=/path/to/memory

Layout:

~/.agents/memory/
  memory.json
  bundles/
    project/
      index.md
      log.md
      decisions/
        runtime.md
  .soul/
    indexes/
    locks/
    settings.json

Rules:

OKF bundles are the source of truth.
.soul/ is rebuildable technical state.
No adapter writes bundles directly.
If cache/index state is deleted, The Soul can rebuild it from bundles.

Protocol

The Soul Memory Protocol is the stable task layer between agents and memory.

Current protocol version: 0.1.

Task families:

remember.classify;
remember.patch;
remember.commit;
search.query;
read.context;
ingest.extract;
lint.review;
migrate.plan.

MCP remember and ingest are task-producing surfaces. Durable writes happen through remember.commit via the core patch/commit path, CLI patch files, or the hook-job consumer after an accepted structured patch.

More: docs/protocol.md

Versioning

The Soul package version follows supported OKF version.

Example:

OKF 0.1 -> The Soul 0.1.0, 0.1.1, 0.1.2
OKF 0.2 -> The Soul 0.2.0, 0.2.1
OKF 1.0 -> The Soul 1.0.0, 1.0.1

Rules:

major.minor comes from the current supported OKF version.
patch increments per release on main.
release CI verifies the deterministic boundary matrix and dry-runs the npm package before bump/tag/publish steps;
bun run certify:agents separately checks live local Claude/Codex subscription auth and structured-output compatibility. It is not a GitHub gate.

Troubleshooting

Run:

soul doctor

Common fixes:

| Symptom | Check | |---|---| | soul not found | reinstall globally or check package manager global bin path | | no memory folder | run soul init | | adapter not active | run soul install <agent> again, then soul doctor | | search finds nothing | check ~/.agents/memory/bundles/ contains OKF markdown | | write blocked by version | run soul migrate plan | | memory busy | another process holds the write lock; retry after a short delay | | local agent certification fails | run command -v claude and command -v codex; verify the selected CLI and its runtime are on PATH, then sign in locally |

Safety and privacy

The Soul is local-first.

It does not need a hosted service to read or write memory.

Safety rules:

no raw conversation archive by default;
remember durable knowledge, not chatter;
no direct adapter writes;
structured patches for writes;
global lock;
atomic writes;
OKF validation;
local cache is rebuildable.

You still own privacy decisions:

do not store secrets;
do not store accidental sensitive content;
review agent-proposed memory when in doubt;
keep memory folder permissions sane.

Development

bun install
bun run typecheck
bun test
bun run verify
bun run release:dry-run

No push or npm publish should happen from local development by default.

License

MIT.