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
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
| Pillar | Tools | What it does |
|---|---|---|
| Persistent memory | memory.remember / recall / brief / forget | Typed (working, episodic, semantic, task, project), scoped, provenance-tracked, supersede-not-delete; refuses to store secrets; hybrid FTS5 and vector recall |
| File intelligence | files.index / search / similar / stats | Incremental hashing, chunking, embeddings, import and similarity edges |
| Task ledger | tasks.create / update_step / resume / handoff / list | Resume packs that survive session death; lease-based single-writer locking so two agents can hand off |
| Safe execution | exec.propose / run_approved, approvals.pending / decide | Deterministic 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-cinterpreter 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.
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.