[ANN] Project Journaling Protocol (PJP): Persistent Memory for your AI Pair-Programmers

Community
1

Hello Crystal community! 0/

As our projects grow, many of us are starting to use AI agents (like Gemini, Claude, or GPT) to help with refactoring, shard development, and boilerplate. However, we’ve all hit the same wall: Context Drift.

After a few sessions, the AI “forgets” why we chose a specific architectural path, or it forgets that one weird “gotcha” we found in a C-binding three days ago.

Inspiration

This project was sparked by a recent discussion on the Crystal Forum with xalynn. The conversation highlighted a critical gap: standard documentation is written for humans, but AI agents need something more condensed, structured, and persistent.

To solve this, my partner (an AI agent) and I have developed the Project Journaling Protocol (PJP). It’s a concurrency-safe, LLM-efficient project memory system that lives inside your repository.

What is PJP?

PJP is a structured way for AI agents to maintain a “Working Memory” and a “History Ledger” that persists across sessions. It doesn’t use complex databases; it’s just a simple directory structure with YAML and Markdown files, optimized for AI ingestion.

The Architecture:

  • .agents/journal/state.yaml: A “whiteboard” for current objectives and blockers.
  • .agents/journal/*.md: Atomic, timestamped Markdown files containing the history ledger.

The Tool: ajourn

We’ve built a tiny, Fedora-native Bash script called ajourn that handles the logging. It uses UUIDs to prevent race conditions when multiple agents are working on the same repo.

Why this matters for Crystal:

Crystal projects often involve complex type systems, C-bindings, and performance-critical decisions. PJP ensures that the technical rationale (the “Why”) is preserved right next to the code (the “What”).

Example “Agent-Speak” Entry:

Agents log using a telegraphic vocabulary to save tokens:

DEC: Use SHA-256 for Git object format.
RAT: Fedora 43 security mandate.
GOT: D-Bus 'ls' command conflicts with local aliases.
PRB: Missing libssl headers in the build environment.

Feedback & Discussion

We are already using PJP to manage its own development. You can find the specification and the ajourn tool here: https://gitlab.com/renich/pjp

I’d love to hear your thoughts!

  1. How do you manage AI context in your Crystal workflows?
  2. Does this “Resident Memory” approach make sense for your projects?
  3. What other “Agent-optimized” patterns should we consider?

– Renich & Gemini

1 Like