evo

evo is a provider-neutral memory service with a Cordis plugin and a native DeepSeek Harness
adapter. It recalls durable memory into the system prompt before a
model step, and reflects completed turns into structured memory afterwards — so an agent keeps what
it learned across sessions without you writing it down.

Renamed: this project was published as evo-memory until 0.2.x. The old data directory, the
old EVO_MEMORY_* environment variables, and the old /evo-memory/* HTTP prefix all still work —
see Migrating from evo-memory.

Contents

• Features · Requirements · Install · Quick start
• How it works · Workspace import · Settings panel
• Claude Code hook · Codex plugin · HTTP API
• Configuration · Service API · Scopes
• Privacy · Limitations · Development · License

Features

• Recall + reflect loop. Memory is assembled into the system prompt on every turn, and each
  successful turn is distilled back into structured memory items.
• Structured, not a scratchpad. Every item has a scope, a kind (fact, constraint,
  procedure, skill, …), tags, and a source pointing at the session and turn it came from.
• Local by default. Storage is a single SQLite file via Node's built-in node:sqlite — no
  native addon, no service to run, nothing leaves the machine except the reflection model call.
• Workspace import. Existing CLAUDE.md, AGENTS.md, .codex/, .copilot/, .agent/, and
  .paper/ files in a project are imported as project-scoped memory on first use.
• Provider-neutral core. The domain model depends on interfaces (MemoryStore, ModelRunner,
  MemoryMaterializer, MemoryEventSink); SQLite and DeepSeek Harness are implementations.
• Native web panel. A Settings → Memory page plus a composer status chip, shipped as a
  plain-JS client half with no extra build step.
• Claude Code and Codex plugin. One hook bridge, shipped as a plugin to both CLIs: it
  recalls memory into a session and distils finished turns back into it, using whichever CLI
  it runs under — and that CLI's own credentials.

Requirements

• Node.js 22.19 or newer
• DeepSeek Harness 0.1.x (for the adapter and the web panel)
• A configured Harness LLM provider and model for reflection and consolidation

The Cordis plugin and the core work without Harness; the Harness pieces are optional peers.

Install

pnpm add evo

From a local checkout, before publication:

pnpm add /absolute/path/to/evo

Quick start

DeepSeek Harness, via the installer

For an npx-managed Harness profile, run the installer from a checkout:

./install_evo_dsps.sh

It builds the package, installs a local link through the official dsh plugin command, and
activates evo as a DSH bundle. The default profile is web; override it with DSH_PROFILE=tui
or another profile name. The script never edits the profile's user cordis.patch.yml.

The bundle uses deepseek-official and deepseek-v4-flash by default; override them at launch
with EVO_PROVIDER and EVO_MODEL.

DeepSeek Harness, by hand

Add the plugins after the Harness LLM and system-prompt services:

- id: evo
  name: evo/cordis
  config: {}

- id: evo-deepseek
  name: evo/deepseek
  config:
    provider: deepseek-official
    model: deepseek-chat
    recallLimit: 40
    maxContextChars: 6000
    reflect: true

# Optional: carries the Settings → Memory web panel. The bare package name is
# required — the client-modules scan only discovers dsh.client bundles there.
- id: evo-web
  name: evo
  config: {}

examples/cordis.yml has a copyable fragment.

How it works

The adapter uses official Harness extension points only:

Interrupted, aborted, rejected, and failed turns are never reflected.

Workspace import

When a session opens in a project working directory (session.header.cwd), the adapter imports the
project's existing agent memory and skill files into the project scope on the first prompt assembly.
The imported knowledge is then recalled like any other memory — no configuration required.

Each file becomes one memory item titled with its path relative to the workspace root, tagged
workspace-import plus tool:<tool>, and sourced with runtime: 'workspace-import' and the
absolute file path. YAML frontmatter is stripped; *.memory.md skill-experience files and empty
documents are skipped.

Import is idempotent: items are upserted by (project scope, title), changed files update in place,
and removed files are never deleted. A project is imported once; re-scan with force:

await ctx.evo.importWorkspace('/workspace/app', { force: true })

Disable the automatic import with workspaceImport: false in the evo-deepseek config.

Settings → Memory panel

The package ships a web client half (dsh.client + exports["./client"]) that adds a Memory
page to the Harness GUI Settings section: the memory list (kind tabs + search), the recent
reflect/consolidate activity log, and actions to consolidate a scope or force a workspace re-import.
It is served by the DSH client-modules mechanism at /plugins/evo/client.js and needs no separate
build step.

In a live conversation the composer tool row also gets an evo chip that keeps the mark visible
and pulses while evo is reflecting or consolidating (it polls /evo/status). Clicking it opens the
Settings → Memory page.

The client half is carried by a no-op Loader row named by the bare package (evo-web in
cordis.patch.yml): the client-modules scan discovers dsh.client packages only through bare
package names, so a subpath row like evo/cordis cannot carry a web client. Restart Harness after
upgrading so the new boot graph includes the panel.

Claude Code hook

evo also plugs into Claude Code (CLI and desktop, which share ~/.claude/settings.json)
through its hook system — no Harness, no web server, no API key of its own.

Install it as a plugin:

/plugin marketplace add TIZ36/evo
/plugin install evo

or patch the settings file directly with the installer:

./install_evo_claude.sh              # install or upgrade, for every project
./install_evo_claude.sh --uninstall  # remove evo's entries again

Use one or the other. Both at once makes evo run twice per turn.

The installer builds the package and patches the user-level
~/.claude/settings.json (override the location with CLAUDE_CONFIG_DIR). It is
meant to be re-run: evo's own entries are replaced with the current set — hook
events added by a later version included — while every other hook in the file is
kept as it is. The previous file is copied to settings.json.evo-backup first,
and the installed command is probed before success is reported.

To wire it by hand instead, or to scope evo to a single repository through that
project's .claude/settings.json:

{
  "hooks": {
    "SessionStart":     [ { "hooks": [ { "type": "command", "command": "evo-hook", "timeout": 20 } ] } ],
    "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "evo-hook", "timeout": 20 } ] } ],
    "Stop":             [ { "hooks": [ { "type": "command", "command": "evo-hook", "timeout": 20 } ] } ]
  }
}

hooks entries are arrays, so this coexists with hooks you already run. A
copyable file is in examples/claude-code-settings.json.
evo-hook is the package's bin; from a local checkout use
node /path/to/evo/dist/hook/cli.mjs as the command instead. Installing both
globally and per-project makes evo run twice per turn — pick one.

Reflection runs through the local claude -p CLI, reusing the credentials Claude
Code already has (under Codex it is codex exec instead — see
Codex plugin). It takes several seconds, so the hook returns
immediately and the work continues in a detached process — a session is never
blocked by evo. The child runs with EVO_HOOK_DISABLE=1 so its own hooks exit at
once; without that guard reflection would recurse.

Turns are distilled in batches, not one by one. A single turn is thin material:
what earns a place in memory — the pit stepped into three times, the convention
confirmed again — only becomes visible across turns, and reflecting per turn pays
a model call to miss it. A batch is distilled once it holds EVO_HOOK_BATCH_TURNS
turns, once those turns add up to EVO_HOOK_BATCH_CHARS characters, or once it
has sat idle for EVO_HOOK_BATCH_IDLE_MS.

That last condition is checked, never fired: a hook is a fresh short-lived process,
so no timer survives between turns. Later hook events settle the deadline instead —
a prompt settles the project it belongs to, and a session start settles every
project left hanging when work stopped. Set EVO_HOOK_BATCH_TURNS=1 to distil
turn by turn as before.

The reflector is told which memories the scope already holds and how many it may
return. Both bounds matter: blind to the store it renames yesterday's fact into a
new row, and uncapped it quotes one long answer back as eight durable memories. It
may also name memories the batch disproved, which are then dropped — but only ones
evo distilled itself. Imported workspace files are a projection of what is on disk;
evo never evicts them, or one reflection could delete your own rules.

As a plugin

The repository is also a plugin marketplace: .claude-plugin/marketplace.json
offers a single plugin whose source is plugin/, holding both hosts'
manifests, hooks/hooks.json, and one dependency-free bundle at
plugin/bin/hook.mjs. Codex installs that same directory.

That bundle is committed on purpose. Both hosts install a plugin by copying the
repository: they run no build step, and Claude Code restores dependencies only
for npm and bun lockfiles, never pnpm. So the plugin has to be runnable exactly
as checked in — pnpm build regenerates it, pnpm test fails if it drifts from
the source, and the hook commands address it through
${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}} (Codex exports the first, Claude Code the
second) so no machine path is ever written down.

What you see

Recall is silent: memory arrives as context, not as UI noise. evo speaks in the
transcript only twice — through the hook's systemMessage, which Claude Code
renders as its own line:

• after a turn it learned from, on your next prompt: evo · remembered 2, updated 1
• when it is broken: evo · memory unavailable: <reason>

Reflection finishes after its turn is over, so its result is left as a
breadcrumb next to the database and reported once on the following prompt, then
cleared. SessionStart never reports it — Claude Code consumes that event's
output without rendering a system message.

Failures never interrupt a session: the hook always exits 0, and the full error
goes to <dataDir>/hook.log.

Project memory is keyed by the canonical (symlink-resolved) working directory.
When a project moves, or was first recorded through a different path, re-point
its memories with:

node scripts/migrate-project-scope.mjs --from /old/path --to /new/path   # add --apply to write
node scripts/migrate-project-scope.mjs --canonicalize                    # add --apply to write

Codex plugin

The same bundle is a Codex plugin. plugin/ carries both manifests
(.claude-plugin/plugin.json and .codex-plugin/plugin.json) over one
hooks/hooks.json and one bin/hook.mjs, and the repository is a marketplace
for either host — .claude-plugin/marketplace.json for Claude Code,
.agents/plugins/marketplace.json for Codex.

Install it the same way, from the CLI:

codex plugin marketplace add TIZ36/evo
codex plugin add evo@evo

or patch the hooks file directly with the installer:

./install_evo_codex.sh              # install or upgrade, for every project
./install_evo_codex.sh --uninstall  # remove evo's entries again

It writes ~/.codex/hooks.json (override the location with CODEX_HOME) and is
re-runnable on the same terms as the Claude Code installer. Codex asks you to
trust a hook command the first time it runs one; until you say yes, evo stays
inert. Use the plugin or the installer, not both.

Three things differ from Claude Code, and evo handles all three itself:

• The transcript. Codex writes a rollout — { type, payload } per line — so
  the turn is read from its event stream, where the prompt has no
  <environment_context> block and reasoning is already split off the answer.
  The format is detected from the transcript's own bytes, so one bundle serves
  both hosts.
• Reflection. It goes through codex exec instead of claude -p, again with
  no key of evo's own. With no EVO_HOOK_MODEL, the model is whatever your Codex
  configuration already selects — evo has no opinion worth hardcoding there.
• codex exec runs no lifecycle hooks. Hooks fire in the interactive CLI, so
  the reflection child cannot recurse even before the EVO_HOOK_DISABLE guard.
  It does, however, wait on piped stdin for input to append to the prompt, so
  evo closes it — otherwise every reflection would hang until its timeout.

Everything else is the same: the same SQLite file, the same scopes, the same
systemMessage line, the same variables in the table above.

HTTP API

The Cordis plugin registers a raw route prefix on the DSH web server when the webServer service is
present (the /api prefix belongs to the DSH web transport, so a plugin bridge uses its own path).
These endpoints are the reserved integration surface for external frontends:

The web server binds loopback by default and every response is JSON. The same data backs the native
Settings panel. The pre-rename /evo-memory/* prefix stays mounted as an alias.

Configuration

With no storage configuration, the SQLite database is created at:

Override the directory with EVO_DATA_DIR or plugin config:

config:
  dataDir: /srv/agent-memory

Override the complete database path when needed:

config:
  databasePath: /srv/agent-memory/team-a.db

Precedence is databasePath, dataDir, EVO_DATA_DIR, EVO_MEMORY_DATA_DIR (legacy), then the
platform default.

Migrating from evo-memory

Nothing is required beyond installing the new package name; the compatibility surface is:

• Database. If the platform default evo/ directory has no memory.db but the pre-rename
  evo-memory/ directory does, evo keeps using the old file. Move it to the new directory whenever
  you like — nothing else points at it.
• Environment. EVO_MEMORY_DATA_DIR, EVO_MEMORY_PROVIDER, and EVO_MEMORY_MODEL are still
  read, after their EVO_* counterparts.
• HTTP. /evo-memory/* still answers alongside /evo/*.

What does change: the package name (evo), the plugin rows (evo/cordis, evo/deepseek, and the
evo-web carrier), and the Cordis service key (ctx.evo, formerly ctx.evoMemory). Re-run the
installer, or update the plugin names in a hand-written cordis.patch.yml.

Service API

The Cordis plugin registers ctx.evo:

await ctx.evo.remember({
  scope: { type: 'project', id: '/workspace/app' },
  kind: 'constraint',
  title: 'Verification',
  content: 'Run the full check command before reporting completion.',
})

const items = await ctx.evo.recall({
  scopes: [{ type: 'project', id: '/workspace/app' }],
  text: 'verification',
})

await ctx.evo.consolidate({ type: 'project', id: '/workspace/app' })

The core exports MemoryStore, ModelRunner, MemoryMaterializer, and MemoryEventSink. SQLite
and DeepSeek Harness are implementations behind those interfaces, not dependencies of the memory
domain model.

Memory scopes

The core supports global, user, project, session, and conversation scopes. The DeepSeek
adapter writes completed-turn reflection to the project scope when session.header.cwd exists, and
to the global scope otherwise. Recall combines global, project, and current-session scopes.

Privacy and safety

Reflection prompts explicitly reject secrets, credentials, raw logs, guesses, and transient task
state. The SQLite database stays local. Model-based reflection still sends the completed turn to the
configured Harness model provider — disable it with reflect: false when that is not acceptable.

Materialized Markdown is deliberately not a source of truth in v1. Structured storage remains
authoritative.

Limitations

• Recall is deterministic SQLite filtering and ranking, without embeddings.
• Reflection runs once per successful turn; queueing and sleep consolidation are not included yet.
• Consolidation is not scheduled automatically; call consolidate() explicitly.
• Claude Code and Codex are supported through the hook plugin; there are no Paper, MCP,
  remote-store, or synchronization adapters yet.
• node:sqlite is still marked experimental by current Node releases even though it ships with
  Node 22+.

Development

pnpm install
pnpm check          # test + typecheck + build + rule scan
pnpm pack --dry-run

The design authority is docs/reference/evo-reference.md.
Open-source boundaries and storage decisions are recorded in
docs/design-principles.md and
docs/storage-architecture.md.

Contributions are welcome — please run pnpm check before opening a pull request, and keep changes
scoped to one topic per PR.

Project rule

This is a personal open-source project. Company identity and sensitive information — company names,
brands, domains, mailboxes, employee names, internal codenames, intranet addresses, or machine
absolute paths — must never appear anywhere in the repository, including built artifacts. Team
attribution is "Paper team" only. The rule is enforced by
scripts/iron-rule.mjs: the source tree is checked on pnpm test, and the
full tree including dist/ is checked by pnpm check.

License

MIT © TIZ36