Back to AI Research

AI Research

PROJECTMEM: A Local-First, Event-Sourced Memory and... | AI Research

Key Takeaways

  • PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents AI coding assistants are highly effective during a single session, bu...
  • 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.
Paper AbstractExpand

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: this https URL .

PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents
AI coding assistants are highly effective during a single session, but they often struggle with "amnesia" when a session ends. They frequently re-read project files, re-derive architectural decisions, and repeat debugging attempts that have already failed. This process is not only inefficient but also consumes thousands of tokens per session. PROJECTMEM addresses this by providing a local-first, event-sourced memory layer that allows AI agents to remember project history, learn from past failures, and act with better judgment across different sessions.

A Persistent Memory Substrate

Instead of relying on complex vector databases or cloud-hosted services, PROJECTMEM uses a simple, append-only plain-text log. Every development action—such as opening an issue, attempting a fix, or making a decision—is recorded as a typed event. Because this log is stored as human-readable text (JSON Lines and Markdown), it is easy to audit, version-control with Git, and search using standard tools. This approach ensures that the agent’s memory is immutable and deterministic, meaning the summaries provided to the AI are always accurate reflections of the project's actual history.

Memory-as-Governance

The most distinct feature of PROJECTMEM is its "judgment layer." Rather than just acting as a passive database that answers questions, the system functions as a pre-action gate. Before an agent performs an action, the system checks the event log for any previously failed attempts or known issues associated with the target file. If a match is found, the system warns the agent, preventing it from repeating the same mistakes. This shifts the role of memory from simply providing information to actively governing the agent's behavior to ensure engineering correctness.

Local-First and Tool-Agnostic

PROJECTMEM is designed to run entirely offline, ensuring that sensitive or proprietary code remains private. It uses the Model Context Protocol (MCP) to serve memory to any compatible AI client, and it includes a universal Markdown bridge for tools that do not support MCP. The system also features cross-project memory, where library-level lessons learned in one repository can be automatically surfaced in another project that uses the same dependencies. Additionally, it includes built-in secret redaction, which automatically scrubs credentials or tokens before they are written to the log, making it safe for use in repositories that are eventually pushed to version control.

Implementation and Evaluation

The system is implemented as a lightweight Python package with minimal dependencies. It supports automated workflows through Git hooks that classify commits into events and an optional file-churn watcher that tracks high-activity files. In a two-month self-study across 10 different projects, the authors logged 207 events to evaluate the system's effectiveness. The implementation includes 37 automated tests and provides a visual dashboard that allows developers to see failure heatmaps, ROI metrics, and project timelines, making the accumulated memory transparent and easy to review.

Comments (0)

No comments yet

Be the first to share your thoughts!