[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

2

This comment may be a bit off to the side, but I do understand the basic idea behind PJP.

I think the reason we want to preserve important information is that it is costly to step back and re-evaluate the whole project every time. That is why people want to accumulate what they have learned, along with decisions that have already been made, so they can refer to them again in the next session.

But I also think there is another possible direction. Instead of storing important points so they are not forgotten, we could make it cheap to re-scan the whole project whenever needed.

What I have been paying attention to personally is not so much coding agents themselves, but the normal web version of ChatGPT. If I put the whole source tree into a tarball, upload it, and ask it in thinking mode to inspect the project, it often grasps the overall structure and gives an evaluation surprisingly quickly. I use a tarball simply because there is a limit on how many files can be uploaded. At least in my impression, it behaves a little differently from a coding agent.

I do not really know why this is possible. But I suspect the web version of ChatGPT is built for somewhat different use cases than coding agents. For example, it may be designed to read large numbers of PDF documents, understand the overall picture, and pull out the details that matter. That kind of ability may also help with code understanding.

Of course, this approach only works when you are building something whose code can be shared openly, and it cannot fully recover past design decisions or every small pitfall. Still, ChatGPT can also refer to information and codebases on the internet, so it is often easier to compare design ideas with libraries in other languages.

AI is moving very quickly, so workarounds like this may soon become unnecessary.

(Translate from Japanese to English with ChatGPT)

3

Thank you.

Indeed, you understand well the idea behind the project. It’s like a journal of really important stuff that is cheap to read for an LLM.

I have done the same as you. I’ve uploaded code to the web version of Gemini. It has access to the search engine via BigQuery so it’s really useful. It definitely has another perspective.

But, when it comes to changes in the code across time, it’s not useful. It doesn’t have a history of the code and knows nothing about why changes were made, at what point and if experiments failed or not. It only sees the actual snapshot.

Without a doubt, it will provide good insight of the current snapshot but it will be an uninformed one. At least not as well informed as I hope PJP-backed agents will be.

So far, it’s been working nicely for me. Agents seem to be aware of things between sessions thanks to the hook that injects context at startup.

4

I agree with your core philosophy. Ultimately, what makes a “good programmer” and the habits that support them won’t change even in 20 years. LLMs will remain a tool to get things done.

However, I have a small correction regarding one point.

It doesn’t have a history of the code and knows nothing about why changes were made, at what point and if experiments failed or not. It only sees the actual snapshot.

You mentioned that LLMs only see a “snapshot” of code, but that isn’t entirely accurate. For example, ChatGPT can deploy code to its workspace and check the git log to understand why changes were made. It even searches the internet to clarify uncertainties. In my experience, it rarely confuses similar languages like Ruby and Crystal.

In contrast, Gemini seems more restricted, especially with its search capabilities. Based on my personal experience:

  • ChatGPT is better at deep thinking and searching.
  • Claude is better at UI design, coding conventions, and tool usage.
  • Gemini excels in areas that don’t compete with search ads, like NotebookLM for podcasts or Nano Banana for illustrations.

This trend has continued for a few years. I’m not sure yet if this is a classic case of the “Innovator’s Dilemma” or if Google is simply waiting for the right time to unlock its full potential.

(Translate from Japanese to English with Gemini :wink: )

5

Yes, you’re correct. They do look at git. But just a little bit. They don’t really dig into it unless you tell them too. In fact, I have caught them being lazy. :slight_smile: