I built pi-persistent-intelligence after running into the same problem on long coding projects: the agent could help in the moment, but it kept losing the decisions that made the work safe. It would forget naming rules, project constraints, previous debugging outcomes, release habits, and the small corrections that only appear after a few days of real use.

That sounds like a productivity annoyance, but it becomes a system problem quickly. If an agent forgets why a decision was made, it may reopen settled work. If it remembers something wrong, it can turn a bad assumption into policy. So the goal was not to give the agent a giant scrapbook. The goal was to build memory with review, evidence, correction, and retrieval as first-class concerns.

The first rule: memory is not automatically true

A lot of memory systems treat capture as the hard part. I treated capture as the risky part. Anything a model stores can be incomplete, stale, or based on a misunderstanding. That is why pi-persistent-intelligence uses a promotion flow: candidates can be captured during work, but durable memory needs structure and review.

The package separates daily session context from long-term records. Daily memory is useful because it keeps the current work coherent. Long-term memory is more sensitive because it affects future sessions. A rule such as "always run bun test before publishing" is useful. A rule such as "this project no longer supports X" can cause damage if it is wrong. Those two records should not have the same path into the system.

Why JSONL became the source of truth

I chose JSONL because it is boring in the right way. Each record is a line. It can be inspected with standard tools, diffed in git, backed up without a database migration, and transformed later if the schema changes. Markdown projections are useful for reading, but they are not the canonical store. That rule matters because humans edit markdown too easily, and once a rendered view becomes the source of truth, structured memory starts to drift.

The records carry fields such as confidence, tags, scope, memory type, evidence, and lifecycle state. That makes retrieval more useful than keyword search alone. The agent can ask for project rules, recent corrections, contested items, or release workflow notes instead of pulling an undifferentiated blob of text into context.

{"kind":"instruction","ruleType":"testing","scope":"project","claim":"Run bun test and bun run typecheck before publishing.","confidence":0.91,"evidence":["prepublish gate"],"status":"active"}
{"kind":"correction","ruleType":"architecture","scope":"project","claim":"Rendered markdown is not canonical. JSONL is the source of truth.","confidence":0.92,"status":"active"}

The inbox is where the human stays in control

The inbox is deliberately frictional. It gives the agent a place to propose memory without silently changing future behavior. A human can approve, skip, revise, or defer an item. That keeps the memory store from becoming a pile of model guesses. It also makes the agent easier to correct because corrections become durable records instead of one-off scoldings in a chat transcript.

Search had to explain itself

Retrieval is where memory either helps or becomes noise. I built session search and recall diagnostics so the agent can inspect why a piece of context appeared. If a record is stale, contested, or low confidence, the system should say so. If a memory came from a specific session or evidence record, that should be visible too.

That design changed how I work with agents. Instead of asking an assistant to "remember this" and hoping it behaves later, I can see the record, the evidence, the confidence, and the retrieval path. The result is less magical and more useful. I prefer that tradeoff.

What I learned building it

The biggest lesson was that agent memory is a governance problem before it is a storage problem. The hard questions are about what should become durable, who can correct it, how stale claims are handled, what evidence supports the record, and how future agents should see it. The implementation is TypeScript and JSONL, but the product is really a set of boundaries around agent behavior.

That is why I still think of pi-persistent-intelligence as infrastructure rather than a feature. It makes the agent less forgetful, but more importantly, it makes its memory inspectable. For long projects, that is the difference between a useful assistant and a confident stranger who keeps starting over.