memoripy: Evidence-Tracked Memory for AI Agents

Overview

Memoripy gives AI agents a local memory layer designed to preserve evidence and explain what was recalled. It addresses common memory failures such as saving noise, treating outdated facts as current, and re-ingesting retrieved memories as new evidence.

The project combines typed, versioned records with scoped retrieval, admission policies, citations, and audit tools. Its core does not require an external model or database, though teams can add optional model providers, a service, MCP support, or PostgreSQL storage.

Key Features

• Admission policies can reject noise, unsupported claims, lower-authority contradictions, and retrieved-memory feedback loops, while quarantining likely secrets and untrusted instructions.
• Bitemporal records and immutable versions preserve how facts change, with separate current and historical queries.
• Retrieval combines independent lanes, including lexical, semantic, entity, temporal, and trust signals, and provides receipts explaining why results were selected.
• User, agent, run, project, organization, and namespace scopes support isolated retrieval.
• CLI audits check for issues such as missing evidence, conflicting facts, sensitive data, expired memories, and citation gaps.
• Correction, explanation, and versioned deletion APIs retain history for inspection.
• Optional HTTP, MCP, tenant gateway, and inspector interfaces extend the local library for services and agent integrations.

Use Cases

• Agent developers can retain user preferences and profile facts while keeping prior values available as historical evidence.
• Teams handling policies or commitments can retrieve current records with supporting citations and inspect their version history.
• Developers integrating external documents can quarantine embedded instructions instead of treating them as trusted user preferences.
• Teams evaluating an existing agent memory store can run CLI audits and memory contracts before migrating.
• MCP-based agent builders can expose scoped memory operations through the optional MCP server.

Getting Started

Install v4 from the repository branch:

pip install "git+https://github.com/caspianmoon/memoripy.git@v4"

See the README for examples, optional extras, and migration guidance.

Alternatives

• EverOS: EverOS stores editable Markdown with local retrieval indexes, rather than screening evidence and tracking cited facts over time.
• Memori: Memori captures conversations and execution context for recall across models and infrastructure, rather than emphasizing local, auditable temporal memory.
• OpenViking: OpenViking organizes knowledge, memories, and skills in a browsable virtual filesystem, with self-hosted or hosted deployment options.
• memvid: memvid is a Rust memory layer that packages content, indexes, and metadata in a portable file, rather than a Python runtime for temporal facts.

Considerations

• The project is active, with recent commits and a recent prerelease, but v4 is still under development and the stable PyPI API may differ. Test the branch and migration path before committing to it.
• Work comes from multiple contributors, with no measured single-contributor concentration. Issue handling has been slow by the available history, so account for that when relying on maintainer responses.
• Python 3.10 or later is required. No GPU or database is required for the core; PostgreSQL, service, and MCP dependencies are optional.
• The deterministic extractor is not general language understanding, and its local hashed embedding is described as a fallback rather than a substitute for a high-quality embedding model.
• The gateway is a self-hosted API-key authorization layer, not a complete hosted or enterprise identity platform. The README recommends TLS and an appropriate reverse proxy for deployment.
• Forgetting creates a versioned deletion rather than irreversibly erasing evidence. Applications with strict deletion requirements need a separate privacy and legal process.
• The project is licensed under Apache-2.0; review the license terms for your distribution and deployment.