PriorStates 0.1.14: A Shared Memory and Journaling Platform for AI Agents

Overview

The Python ecosystem continues to evolve with tools that help developers manage the state of AI agents across sessions. The newly published PriorStates 0.1.14 package on PyPI introduces a lightweight solution that combines shared memory, a research journal, and a cockpit interface. Designed for Claude, Codex, and Gemini, the library also integrates a runnable markdown environment, offering a seamless way to persist and retrieve information while keeping the workflow organized.

The approach is particularly useful for long‑running experiments where state continuity is critical.

Core Concepts

• Shared Memory – A persistent store that lets multiple instances of an AI agent access the same data without requiring external databases.
• Research Journal – A chronological log where each entry captures observations, experiments, and outcomes, searchable by keyword or timestamp.
• Cockpit – A simple dashboard that visualizes current memory state, recent journal entries, and allows quick edits.
• Runnable Markdown (mdlab) – An embedded markdown interpreter that can execute code snippets, render visualizations, and update the journal directly from text.

How It Works

The library stores data in a JSON file located in the user’s home directory. When an agent starts, it loads the file into memory, making look‑ups instantaneous. New entries are appended to the journal and written back to disk in a single atomic operation, ensuring consistency even if the process is interrupted. The cockpit provides a REPL‑style interface that accepts commands such as list, search, and edit, each of which manipulates the underlying store.

A notable feature is the markdown interpreter. By embedding fenced code blocks with language identifiers, users can trigger Python code, generate plots, or format tables. The output is captured and inserted into the journal, creating a living document that blends narrative with executable content.

Benefits for Developers

• Persistence without overhead – No need to set up a separate database; the file‑based approach works out of the box.
• Traceability – Every change is timestamped and signed, making it easy to audit the agent’s evolution.
• Collaboration – Multiple agents can share the same memory file, facilitating teamwork on complex tasks.
• Rich documentation – The runnable markdown turns notes into interactive reports, useful for both developers and stakeholders.

Integration with Major AI Platforms

The package includes adapters for Claude, Codex, and Gemini. Each adapter exposes a simple API that the agent can call to query memory, append journal entries, or request cockpit updates. For example, a Codex‑based coding assistant can log each function it writes, then later retrieve the full history to suggest improvements. Similarly, a Claude‑powered chatbot can reference previous conversations to maintain context across sessions.

Getting Started

Installation is a single pip command:

pip install priorstates

After installation, initialize a new memory store:

priorstates init

This creates a ~/.priorstates/ directory with a default JSON file. Launching the cockpit:

priorstates cockpit

opens a terminal interface where users can start recording entries. Detailed usage instructions are available in the README on the PyPI page.

Community and Future Directions

The project is open source and hosted on GitHub, encouraging contributions from the AI research community. Planned enhancements include encrypted storage for sensitive data, a web‑based cockpit, and tighter integration with popular notebook environments. Feedback from early adopters will shape the roadmap, ensuring the tool remains aligned with real‑world needs.

Takeaway

PriorStates 0.1.14 offers a compact, file‑based solution that unifies memory, journaling, and interactive documentation for AI agents. By providing ready adapters for leading models and a runnable markdown environment, it reduces the friction of persisting state and enriches the documentation process. Developers seeking a lightweight way to give their agents a persistent memory without the complexity of external databases will find PriorStates a practical addition to their toolkit.