Technical Summary: projectmem

Problem Statement

AI coding assistants, while powerful within a single session, suffer from a critical architectural flaw: they are stateless across sessions. When a conversation window closes, the agent loses durable project-specific state. Consequently, subsequent sessions often require the agent to re-read source files, re-ask questions answered previously, and, most cost-effectively, re-attempt fixes that have already failed.

This is identified not as a model-quality issue but as an architecture problem. Reconstructing context by re-reading a project consumes an estimated 5,000–20,000 tokens per session. Furthermore, existing memory solutions often rely on vector databases or LLM-in-the-loop fact extraction, introducing nondeterminism, recurring read costs, and a lack of local-first privacy. Crucially, current systems primarily act as passive "Memory-as-Tool" (answering queries) rather than active "Memory-as-Governance" (intervening before an action to prevent known failures).

Methodology and System Design

The paper presents projectmem, an open-source, local-first memory and judgment layer for AI coding agents. The system is built on four core design principles:

1. Immutability: Memory is an append-only event log, never edited in place, creating a replayable audit trail.
2. Human Legibility: The log is plain text (JSON Lines + Markdown), making it grep-able, diff-able, and version-controllable via Git.
3. Locality: All state resides in the repository and the local machine with no network dependency or telemetry.
4. Determinism: Summaries and judgment gates are pure projections of the log, not LLM-generated outputs.

Core Components

• Event-Sourced Substrate: Development is recorded as typed events: issue, attempt (with outcomes: worked/failed/partial), fix, decision, and note. These are appended to events.jsonl.
• Deterministic Projection: A summary file (summary.md) is regenerated deterministically from the event log. This ensures the agent reads a consistent, derived state that cannot drift from the underlying history.
• Judgment Layer (Memory-as-Governance): The system introduces a deterministic pre-action gate. Before an agent touches a file, the precheck_file(path) function consults the event log for failed attempts, open issues, or high churn associated with that path. It returns a warning (e.g., "you tried this 2 days ago—it failed") without making an LLM call.
• Cross-Project Memory: Lessons learned in one project (e.g., library-specific gotchas) are filtered and promoted to a machine-wide global store (~/.projectmem/global). These are automatically surfaced in other projects using the same stack, keyed by library manifests (e.g., package.json, pyproject.toml).
• MCP Integration: The system runs as a native Model Context Protocol (MCP) server, exposing 14 typed tools (9 read, 5 write) to any MCP-capable client (e.g., Cursor, Claude). It also includes a Markdown bridge for non-MCP tools.
• Security: Secret redaction is enabled by default, scrubbing tokens and keys from event text before they are written to the log.

Key Contributions

The paper outlines four primary contributions:

1. Event-Sourced Memory Substrate: A plain-text, append-only log of typed events that replaces vector databases, enabling deterministic projection of compact, AI-readable summaries.
2. Judgment Layer: A deterministic, history-derived pre-action gate that warns agents before repeating failed fixes or editing fragile files, operationalizing the concept of "Memory-as-Governance."
3. Local-First, Tool-Agnostic System: A native MCP server and universal Markdown bridge that runs fully offline with default-on secret redaction.
4. Implementation and Evaluation: A three-dependency Python package (14 MCP tools, 19 CLI commands, 37 automated tests) evaluated through a two-month self-study.

Results and Evaluation

The authors evaluated projectmem through token-cost analysis and a self-study across 10 real-world projects (ML, web apps, research code) over two months (March 30–May 29, 2026).

• Token Cost Reduction: In MCP mode, the agent loads roughly 800–1,500 tokens per session via get_summary(), compared to an estimated 5,000–20,000 tokens required to reconstruct context without a memory layer. This represents an estimated reduction of over 50% in token usage per session.
• Self-Study Data: The system accumulated 207 real events across 10 projects. The event composition was dominated by durable notes and decisions (61%), followed by fixes (25%), attempts (5%), issues (5%), and decisions (4%).
• Memory Accumulation: Unlike stateless agents that reset to zero every session, projectmem's memory compounds monotonically, preserving the "issue/attempt/fix" triples and architectural decisions that stateless agents discard.
• Compatibility: The system was verified to serve identical memory to four different MCP-capable clients without modification.
• Auditability: The immutable log serves as a provenance trail, recording what was changed, what was tried, and why, using standard version-control tools.

Significance and Claims

The paper positions projectmem as a practical substrate for auditable, AI-assisted software development. Its significance lies in shifting the paradigm from "Memory-as-Tool" (passive retrieval) to "Memory-as-Governance" (active intervention).

The authors claim that by keeping memory immutable, human-legible, offline, and tool-agnostic, projectmem addresses the "amnesia" of AI agents that leads to repeated failures. It provides a deterministic mechanism to stop an agent from repeating a known mistake before the action occurs, rather than learning from it after the fact. The system is explicitly designed to be complementary to, not a replacement for, embedding-based memory where broad semantic recall is the goal; projectmem prioritizes determinism, legibility, and zero read-time model cost.

The paper remains modest regarding its claims, noting that the token savings are usage estimates rather than controlled benchmark results, and that the judgment gate is advisory by design to avoid false positives on superficially similar but valid new changes. The work is presented as an open-source infrastructure contribution to the field of agentic software engineering.