Case study 01 / 04

Substrate

A local-first layer that gives any MCP-compatible agent persistent memory, a task ledger, file search, and a safety gate for shell commands. 17 tools, no network calls, 58 tests.

Position
Sole developer
Period
August 2026
Stack
  • Python 3.10 to 3.12
  • Model Context Protocol
  • SQLite FTS5
  • pytest
  • ruff
  • GitHub Actions
Status
v0.1 MVP, MIT, 58 tests, no runtime dependencies
Repo
github.com/TirthPatel6104/substrate
Datasheet 01 of 04
Substrate2026

The problem

Coding agents reason well and remember nothing. Every session re-learns the project. Work done in one tool is invisible to the next. Long tasks die when the context window fills. And each agent re-implements, or skips, the question of whether a shell command is safe to run.

MCP standardised how agents call tools. Substrate is the stateful local layer under them: no chat loop, no model of its own, just the parts every agent needs and none of them keep.

Four pillars, seventeen tools

PillarToolsWhat it does
Persistent memorymemory.remember / recall / brief / forgetTyped (working, episodic, semantic, task, project), scoped, provenance-tracked, supersede-not-delete; refuses to store secrets; hybrid FTS5 and vector recall
File intelligencefiles.index / search / similar / statsIncremental hashing, chunking, embeddings, import and similarity edges
Task ledgertasks.create / update_step / resume / handoff / listResume packs that survive session death; lease-based single-writer locking so two agents can hand off
Safe executionexec.propose / run_approved, approvals.pending / decideDeterministic SAFE / NEEDS_CONFIRMATION / HARD_BLOCK gate in front of a real executor, with a persistent approvals queue and audit log

Everything lives in one SQLite file. Runtime dependencies: the standard library. Network calls with the default config: none.

The safety gate

The part I am proudest of has no model in it, on purpose: the gate has to hold when the model is the thing being attacked. It classifies every command with plain deterministic logic before anything runs, and it assumes the command string is trying to hide something from a naive parser.

  • Chained commands (&&, ;, ||, |, newlines) are split and each piece classified; the worst result wins.
  • Command substitution ($(…), backticks) and -c interpreter payloads are pulled out and classified too, so a dangerous command cannot hide inside a safe one.
  • Unknown commands default to NEEDS_CONFIRMATION, never to SAFE.
  • Danger is judged as operation × target × reversibility. Keyword lists are easy to dodge.

Every bypass found in review (-c payloads, newline splitting, git config as a write, a -v flag that read as safe, mkfs.*) is pinned shut by a regression test.

Try the gate. Type a shell command; the verdict is computed in your browser by a port of the real rules.
Targets system path '~/projects' for deletionHARD_BLOCK
Chained parts, command substitutions, and interpreter -c payloads are each classified; the worst result wins. Unknown commands default to NEEDS_CONFIRMATION.

From the terminal

$ substrate -w demo remember "We deploy with 'make release'; never push to main" --type project --pin
$ substrate -w demo brief
$ substrate -w demo exec "echo hi"                 # SAFE, runs
$ substrate -w demo exec "rm -rf /"                # HARD_BLOCK, refused
$ substrate -w demo exec "pip install requests"    # NEEDS_CONFIRMATION, queued
$ substrate -w demo approvals

Several agents on one machine can share one daemon (substrate serve --transport http), with a local web page for the approvals queue and lease errors that tell the second agent to ask for a handoff.

How it got here

It started as an AI ticket-triage prototype. A written code review of that prototype concluded the useful part was the safety gate, so the project pivoted. Both blueprints and the review are in docs/. I would rather show the pivot than hide it.

Next

Episodic auto-summaries and compaction, plus graph-expansion recall.

More work