Perenna AGENTS.md

Perenna Agent Guidelines

These instructions apply to every change in this repository. Perenna is a Python 3.12+ MCP server that keeps permanent agent memory as Markdown in an independent Git repository and uses Vexor only as a rebuildable retrieval index.

Start with the project contract

Read Contributing before changing code. Its sections on architectural boundaries, Git operations, safety, documentation ownership, and the change workflow are requirements, not background material.

Use the document that owns the part being changed:

• Architecture and Consistency model for storage, snapshots, locking, indexing, and failure behavior;
• MCP API for tool names, schemas, actions, and structured results;
• Memory file format for paths, frontmatter, normalization, identity, and revisions;
• Configuration for CLI flags, environment variables, local paths, synchronization, and provider settings;
• Testing for the current quality gates and test tiers;
• Releasing for versioning, packaging, and the automated publication path.

Do not copy complete contracts between documents. Update the canonical owner and link to it from other surfaces that need context.

Environment

Use uv and the checked-in uv.lock; do not use the system interpreter or install project dependencies globally. Set up the development environment with the command under Set up the repository in Contributing, and run all Python tools through uv run.

Use temporary directories or an explicitly disposable PERENNA_HOME for tests and manual experiments. Never run destructive development checks against the user's normal ~/.perenna data.

Implementation boundaries

• Treat committed Markdown in the configured memory repository as permanent truth. An index, cache, or remote synchronization failure must not disguise or undo an existing local commit.
• Keep the core independent of MCP transport. Preserve both local stdio and single-owner OAuth-protected Streamable HTTP unless an approved product change says otherwise.
• Keep the public surface to memory_read, memory_write, and memory_delete. Do not expose Git or index maintenance as agent tools.
• Preserve exact schemas and strict validation. Reject unknown fields and invalid action combinations instead of guessing or silently degrading.
• Keep mutations revision-guarded, path-scoped, and atomic. Runtime Git code must never merge, rebase, or force-push automatically.
• Do not add speculative compatibility layers, generic transport interfaces, multi-user storage, an authorization server, or bundled TLS/reverse-proxy management without explicit approval.