PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents

Abstract: AI coding assistants now support a growing share of software work, from quick scripts to production applications. Yet these agents remain largely stateless: each new session re-reads project files, re-derives prior decisions, and - most costly - may repeat debugging attempts that already failed. Reconstructing this context can consume an estimated 5,000-20,000 tokens per session; the bottleneck is often not model capability but missing project memory. We present projectmem, an open-source, local-first memory and judgment layer for AI coding agents. projectmem records development as an append-only, plain-text event log of typed events - issues, attempts, fixes, decisions, and notes - and deterministically projects that log into compact, AI-readable summaries served through the Model Context Protocol (MCP). Beyond storage, projectmem adds a deterministic pre-action gate that warns an agent before it repeats a previously failed fix or edits a known-fragile file. We frame this as Memory-as-Governance: memory that does not merely answer the agent but acts on its next action. The system runs fully offline with no telemetry; its immutable log also serves as a provenance trail for reproducible, auditable AI-assisted development. projectmem ships as a three-dependency Python package (14 MCP tools, 19 CLI commands, 37 automated tests) and is evaluated through a two-month self-study across 10 projects comprising 207 logged events. Source code: https://github.com/riponcm/projectmem.

• The paper introduces projectmem, a system that logs development events to provide persistent context and proactive governance for AI coding agents.
• It employs deterministic projections from an immutable, append-only event log to significantly reduce session token costs and enhance auditability.
• Empirical results show over a 50% token cost reduction per session and improved reproducibility via a pre-action judgment mechanism integrated into development workflows.

PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents

Motivation and Problem Statement

The proliferation of LLM-based coding agents has transformed software development workflows, yet these systems are characterized by an acute absence of persistent, cross-session memory. Statelessness at the session boundary leads to repeated context reconstruction, redundant debugging, and substantial token inefficiency. Empirical analyses of agentic pull request failures on real-world repositories repeatedly identify the reapplication of failed patches and the propagation of root-cause errors across sessions as core failure modes for such agents. Existing retrieval-augmented memory architectures and project-specific caches do not sufficiently address these issues, either due to reliance on nondeterministic or mutable retrieval, lack of local-first guarantees, or an inability to enforce proactive action-level constraints.

Design and System Architecture

projectmem introduces an event-sourced, append-only, local-first memory substrate specifically architected for AI coding agents. The system records the software development process as a stream of typed events—issues, attempts, fixes, decisions, and durable notes—with each event capturing temporal, locational, and semantic metadata. This immutable log is human-readable (plain-text JSONL + Markdown), amenable to standard code review procedures, and version-controlled alongside project source. projectmem’s deterministic projection mechanism generates concise, lossless AI-readable context files consumed by the agent, obviating the need for context re-derivation on subsequent sessions.

The architectural pipeline is illustrated in (Figure 1).

Figure 1: The projectmem data lifecycle, including event capture, deterministic projection, MCP-based service, and pre-action governance mechanisms.

Four capture modalities—the CLI, annotated git hooks, file-churn monitoring, and direct MCP tool calls—populate the event log. All subsequent projections (project summaries, structure maps) and agent-facing context are deterministically derived from this canonical log, ensuring invariance and auditability. A plain-text, git-native design guarantees universal legibility and reproducibility.

Memory-as-Governance: Pre-Action Judgment Layer

The core innovation of projectmem exceeds passive memory retrieval. It embodies “Memory-as-Governance,” operationalized as a deterministic, pre-action judgment gate. For every agent-initiated action (or developer commit), the system performs a fixed-cost lookup for prior failed attempts or high-churn files at the prospective edit site. When matches are found, the agent receives an actionable warning (“you tried this 2 days ago—it failed”) before the action is executed. This constitutes a proactive, project-specific, model-free intervention mechanism, distinct from generic, stochastic, or LLM-trained guardrails. The pre-action gate is purely deterministic and derived directly from project-specific historical failure exemplars, providing guarantees on reproducibility and transparency.

Operational Features and Integration

projectmem is distributed as a Python package with minimal dependencies, exposing both a comprehensive CLI and a standards-compliant MCP server with 14 typed tools (9 read, 5 write). Integration is seamless with MCP-capable coding agents, and a Markdown bridge ensures compatibility outside the MCP ecosystem. The initialization routine performs repository backfill, leveraging existing git commit history to instantiate an informative memory state even for legacy codebases.

A cross-project global memory mechanism identifies and promotes library-level lessons (e.g., “this date library drops the timezone unless constructed in UTC”) for recall in any future project with a matching stack, without cloud synchronization or telemetry. Machine-wide lessons are surfaced contextually based on manifest parsing and stack fingerprinting.

Sensitive data is protected via robust, pattern-driven secret redaction, preventing credentials from persisting in any plaintext event log. This is enforced on all write paths.

Empirical Evaluation

Token Efficiency and Memory Accumulation

A salient result is the reduction in per-session context-loading cost. The baseline stateless agent incurs 5,000–20,000 tokens/session (context re-derivation), while projectmem in MCP mode reduces this to a fixed 800–1,500 tokens/session; the Markdown bridge operates near 2,500 tokens/session. These reductions result in an estimated >50% reduction in token cost per session for real use-cases (Figure 2).

Figure 2: Estimated tokens loaded per session across session modes, highlighting >50% reduction by projectmem over stateless operation.

A two-month self-study across 10 heterogeneous projects recorded 207 logged events, showing continuous accumulation of project knowledge (Figure 3). The event-type distribution is dominated by durable notes, decisions, and issue/attempt/fix cycles (Figure 4), reinforcing that projectmem predominantly captures the information that stateless agents systematically discard.

Figure 3: Cumulative event growth in memory across projects, demonstrating compounding accumulation versus stateless agents.

Figure 4: Event-type composition reveals the predominance of durable notes and decisions, along with issue/fix/attempt event triplets.

Auditability and Compatibility

projectmem’s design achieves strong auditability: all AI-driven actions are logged immutably and are directly attributable, supporting reproducibility mandates in LLM-assisted SE. The MCP-conformant implementation is validated across multiple agent clients without configuration modification, facilitating persistent memory continuity even as agent tools change.

Implications and Positioning

projectmem occupies a unique locus in the agent memory design space, characterized by the confluence of local-first operation, deterministic event sourcing, plain-text audit trails, MCP-native integration, and proactive judgment. In contrast to retrieval-based or vector-memory architectures optimized for semantic recall, projectmem prioritizes legibility, determinism, and action-level governance—attributes directly relevant for project correctness and safety in practical software engineering.

Its architecture positions it as complementary to systems like Memanto, MemGPT, or embedding-based fact banks, especially where fine-grained, project-local provenance trails or governance are required. Furthermore, its global-memory mechanism presages incremental transfer learning across user projects strictly via local infrastructure, sidestepping privacy and compliance barriers associated with cloud-hosted solutions.

The theoretical implications extend to the agentic software development paradigm: projectmem advances the interface between memory substrates and agent policy from “passive context augmentation” to “direct governance” by memory, suggesting new directions for action-aware, task-specific regulation beyond generic model alignment.

Limitations and Future Work

Several limitations are acknowledged. The judgment gate is only as informative as its underlying event log and may emit advisory false-positives in cases where prior failures no longer semantically apply. The system is deliberately non-semantic in retrieval—eschewing fuzzy or embedding-based recall—yielding determinism at the cost of recall breadth. Usage metrics are based on estimated token savings, not controlled benchmarks. The current implementation is single-user and locally resident, although the architecture admits extension to multi-user, CRDT-merged logs. Notably, the authors propose future work on measured repeat-failure prevention benchmarks, integration of optional fuzzy semantic retrieval, and extending diffs to fire judgments prior to file-level commit boundaries.

Conclusion

projectmem delivers a robust, event-sourced, local-first memory and governance substrate for coding agents, shifting the memory paradigm from passive retrieval to deterministic, pre-action intervention. Empirical evaluation demonstrates significant reductions in token overhead and structured accumulation of actionable project memory. The system yields both practical and theoretical advancements: practical by granting tool-agnostic, privacy-preserving, reproducible memory for agentic development, and theoretical by advancing the Memory-as-Governance paradigm within the agent architecture landscape. The open-source release enables further research on persistent agentic memory, local provenance trails, and governance-enabled agent infrastructures (2606.12329).