ach-memory

A governed, engine-neutral access and delivery layer for memory engines, used by coding agents over MCP. The engine remembers; ach-memory decides who may read and write which bank, keeps the journal, scrubs secrets, and delivers a bounded standing context at session start. Hindsight is the first engine.

Status: 0.1.0. Contract in SPEC.md; why it looks like this in docs/lessons.md.

agent host (Claude Code, Codex)
  │ stdio                       ┌────────────────────────────┐
  ▼                             │ ach-memory (this service)   │
ach-memory mcp  ── HTTPS/MCP ──▶│  auth → scope → service     │──▶ Postgres
  (proxy: git origin → slug,    │  retain · recall · curation │    users, projects,
   auth header)                 │  standing context           │    journal
                                │  Backend ABC ─ Hindsight    │──▶ Hindsight (banks,
                                └────────────────────────────┘    mental models)

Tools

retain · recall · reflect · forget · restore · correct · delete_memory · list_memories · get_memory · history · load_context · get_operation · rename_project. One MCP endpoint (/mcp/), one health route (/health). No REST data plane.

Related MCP server: semantica

Install on a host

See docs/hosts.md. Short version:

export ACH_MEMORY_URL=https://api.<domain>/ach-memory/mcp/
export ACH_MEMORY_API_KEY=<your platform key>

claude   plugin marketplace add ackstorm/ach-memory && claude plugin install ach-memory@ach-memory
codex    plugin marketplace add ackstorm/ach-memory && codex  plugin add     ach-memory@ach-memory
opencode plugin ach-memory@git+https://github.com/ackstorm/ach-memory.git --global
pi       install git:github.com/ackstorm/ach-memory

opencode also installs straight from the service, with no git and no registry — the endpoint serves the running release's own bundle:

opencode plugin https://api.<domain>/ach-memory/plugin --global

This repository is the plugin bundle: each host reads its own root manifest (.claude-plugin/, .codex-plugin/, package.json) and gets the one skill, the one set of hook scripts, and a stdio proxy built from the checkout it just installed -- so there is no version to pin and nothing of ours to run first.

Run it

make up          # Postgres + Hindsight (mock LLM) + migrations + API on :8000
make e2e         # the same stack, then scripts/mcp-smoke.py over all twelve tools
make test        # unit + contract tests against the fake engine (Postgres on :5434)
MEMORY_HINDSIGHT_URL=http://localhost:8888 uv run pytest -m integration tests/backend

Configure

Every setting is an environment variable with the MEMORY_ prefix (src/memory/config.py). The ones a deployment must set:

Engine profile (verbatim extraction, types=world recall, semantic floor) lives in the Hindsight adapter, not in core; see SPEC.md §5.

Add an engine

Subclass memory.backend.base.Backend in src/memory/backend/<name>.py, add one line to get_backend(), and run the contract suite (tests/backend/test_contract.py) against it. Core never imports a concrete adapter.

Deploy

Helm chart in deploy/helm/ach-memory (image ghcr.io/ackstorm/ach-memory, chart oci://ghcr.io/ackstorm/charts/ach-memory). Release: make release-bump VERSION=x.y.z → commit → make release-cut VERSION=x.y.z; CI publishes the image, the chart and the GitHub release from the tag.