Pathmark

Inspiration

Coding agents are increasingly capable, but every fresh task still starts cold. The project remains on disk while the reasons behind its architecture, constraints, and earlier decisions disappear. Copying context manually is slow, inconsistent, and hard to audit. Pathmark makes that context durable and visible across agents while keeping the source of truth on the developer's machine.

What it does

Pathmark runs as a local MCP server. An agent can save a decision in Session A, end the process, and recover the exact decision from a fresh Session B. Recall includes visible evidence: memory IDs, timestamps, sources, tags, previews, and match metadata.

The Build Week extension makes this suitable for longer-running developer use: namespace-scoped reads and writes, default secret redaction, revision history, superseding, expiration and retention, diagnostics, backup and compaction, preview-first hard purge, optional encrypted portable exports, and safer concurrent SQLite indexing.

How it was built

Pathmark is TypeScript on Node.js 22.5+ and exposes a provider-neutral stdio MCP server. Canonical records are append-only JSONL; SQLite FTS is a disposable derived search index. This keeps the durable state inspectable while preserving fast local retrieval.

During Build Week, Codex with GPT-5.6 audited the live repository, reproduced a multi-process SQLite race, implemented lifecycle and safety controls, added regression coverage, and hardened release delivery with CodeQL, dependency review, immutable GitHub Action pins, OpenSSF analysis, and npm provenance.

The v0.1.8 production pass then fixed a second class of correctness problems found in real Codex memory: visible recall could race with capture of the current prompt, relevance could leak unrelated projects into a workspace-scoped result, and tool activity lacked a structured provenance trail. The release pins visible recall to the exact pre-capture memory IDs, hardens relevance and migration, and adds private-by-default session and tool provenance.

What existed before the challenge

Before the submission window, Pathmark already had a local JSONL store, a derived SQLite search index, MCP memory tools, basic multi-client setup, and visible used-memory tracing. Those features are not presented as new work.

What changed during Build Week

Fixed a reproduced multi-process SQLite index race and restricted recovery to verified corruption.
Added namespaces and default redaction to MCP ingestion and recall paths.
Added updates, revisions, superseding, expiration, retention, diagnostics, backup, compaction, and preview-first hard purge.
Added scoped import/export, optional AES-256-GCM portable exports, local hybrid reranking, and portable harness ingestion.
Added required Node 22/24, dependency review, and CodeQL checks, plus npm auditing, OpenSSF analysis, immutable Action pins, protected tags, and package provenance.
Fixed visible-recall evidence drift by pinning the exact pre-capture memory IDs and removing the redundant full-record copy.
Added multi-concept relevance thresholds, conservative aliases, English/Russian stop words, near-duplicate suppression, project/namespace preference, and explicit cross-project fallback.
Added a session_trace MCP tool and structured prompt, memory, tool-result, and final-answer provenance while keeping tool-output text private by default.
Added bounded activity retention, export/import preservation, parser and cursor migration, a five-query retrieval acceptance corpus, and live process-boundary capture tests.

Pre-challenge baseline: 4c0e87dfdbd2ba4c643abd8b887cc228bdb08b73 (v0.1.5)

Qualifying releases: v0.1.6, v0.1.7, and v0.1.8

Qualifying diff through v0.1.8: 6,681 additions and 283 deletions across 100 files

Challenges

The most important bug did not look like data corruption at first. Two Pathmark processes could open a stale derived index, interpret SQLite BUSY as corruption, rename a healthy database, and trigger competing rebuilds. Codex helped reproduce the failure on isolated data before the recovery logic changed. That led to a cross-process synchronization design that distinguishes lock contention from verified corruption.

The second challenge was destructive memory lifecycle work. Purge and compaction were designed around explicit previews, backups, and scoped operations so an agent cannot silently turn a maintenance request into irreversible data loss.

The third challenge was transparent recall itself. The current prompt could be captured between proactive recall and the visible recall_memory call, replacing the evidence the model had actually seen. v0.1.8 makes that path race-free by preserving the original memory IDs and recalling those exact records. It also prevents relevant workspace results from being padded with unrelated projects and records session/tool provenance without exposing raw tool output by default.

Accomplishments

A real two-process demo recovers a decision from a fresh MCP session with visible provenance.
Secret-shaped input is redacted before storage.
The judge demo uses an isolated temporary store and does not touch normal user data.
The package is dependency-light, MIT-licensed, and works locally without an account or hosted service.
The qualifying release pipeline passed build, runtime, lint, CodeQL, dependency review, audit, package, and provenance checks.
The v0.1.8 retrieval acceptance corpus covers the real production failure modes, and the installed-package canary verifies upgrade migration and live Codex capture across process boundaries.

What I learned

Local-first agent memory is not just a retrieval problem. It is a lifecycle, concurrency, provenance, and trust problem. The useful boundary is not “the model remembered something”; it is “the user can inspect exactly what was stored, why it matched, and how to safely revise or remove it.”

What's next

The next focus is evaluating retrieval quality across larger real-world repositories, strengthening portable integrations for more coding harnesses, and improving user-facing inspection without adding a hosted dependency.

Try it

Repository: https://github.com/hacksurvivor/pathmark

Package: https://www.npmjs.com/package/pathmark

git clone https://github.com/hacksurvivor/pathmark.git
cd pathmark
npm ci
npm run build
npm run demo:build-week

The demo starts the actual Pathmark MCP server twice against one isolated temporary store. Session A saves an architecture decision. Fresh Session B recovers it, displays the evidence used, verifies redaction, and checks store health.