Agent Filetree Memory MCP

Agent Filetree Memory MCP is a framework-neutral memory service for agents. It stores a simple virtual Markdown file tree in PostgreSQL while keeping paths and document content encrypted at rest.

The project is designed around four boundaries:

• The host verifies a short-lived capability and selects the workspace and durable agent profile. Models and UI components cannot choose or widen those identifiers.
• Every document and directory version is immutable and encrypted with a fresh AES-256-GCM data key.
• PostgreSQL is injected through an async SQLAlchemy session factory. Standalone users may construct one from a static database URL; hosting platforms may supply their own credential-aware factory.
• MCP is an adapter. The application service can also be embedded directly in another Python service.

The headless tools support directory browsing, recursive filename and content search, paged reads, exact-text edits, history, writes, appends, and deletion. See the tool contract for parameters, limits, examples, and the 0.6 upgrade notes. History metadata and historical content use separate capabilities. Writes use compare-and-swap versions and idempotency keys. Delete denies access immediately and makes encrypted data eligible for hard deletion after its configured retention window. The host must run the packaged janitor; the request-serving process does not schedule cleanup itself.

Status

This project is an early alpha. APIs, migrations, and data formats may change before 1.0.

Development

With uv installed and Docker running, uv sync --locked followed by uv run python -m devtools.postgres runs the complete test suite against a disposable PostgreSQL instance. No manually managed database is needed. The optional agent eval harness measures real model task success, tool usage, and saved state, with local reports and opt-in Logfire experiments.

Installation

Add the complete package to a uv-managed project:

uv add 'agent-filetree-memory-mcp[all]'

Or install its standalone commands in an isolated environment:

uv tool install 'agent-filetree-memory-mcp[all]'

The base package contains the framework-neutral domain and application layers. The postgres, mcp, app, and web extras are available for narrower integrations. See the standalone guide for database setup, security-sensitive configuration, and server startup.

Intended package layers

• agent_filetree_memory.domain: dependency-light identifiers, paths, results, and errors.
• agent_filetree_memory.application: authorization-first memory operations.
• agent_filetree_memory.crypto: envelope encryption and pluggable data-key providers.
• agent_filetree_memory.postgres: PostgreSQL persistence and packaged Alembic migrations.
• agent_filetree_memory.control_plane: optional workspaces, durable agent profiles, membership, private-by-default workspace-read policies, independent management/content grants, and audit.
• agent_filetree_memory.mcp: headless MCP tools.
• agent_filetree_memory.mcp_app: an optional current-capability browser and editor.
• agent_filetree_memory.web: the version-matched management API composition and bundled React UI.

The package ships schema migrations; the host applies them during deployment. See database migrations and upgrades for the standalone agent-filetree-memory-migrate command and integration with an existing Alembic environment.

Version history and attribution

Every retained document version has a canonical version_created_at timestamp. memory_history_list returns retained versions newest first without returning their Markdown; its metadata includes the caller-supplied change comment, so a host should still treat that capability as potentially sensitive. memory_history_read returns one retained version and can also produce a unified line diff by accepting compare_to_version. Pagination and retention are bounded; history is not an unbounded event log.

Writes and appends may include an optional change_comment and up to eight opaque co_authored_by identifiers. Version responses distinguish the two attribution levels:

• committed_by identifies the authenticated principal whose verified capability committed the version and carries verification: "authenticated";
• each co_authored_by entry is caller-declared and explicitly carries verification: "self_asserted".

Authenticated here means that principal's authorization was used. It does not prove who drafted, typed, or approved the Markdown. The optional change comment is also caller-supplied text, not verified attribution. Versions created before this metadata format remain readable and return unavailable attribution as null/empty values. Current list/read payloads retain updated_at as a compatibility alias for version_created_at.

Security properties

The service authorizes before storage lookup or decryption. Missing and unauthorized documents share the same public failure shape. Database rows contain opaque routing, authorization, version, and lifecycle fields; human-readable paths, titles, tags, snippets, Markdown, and directory manifests are encrypted.

See SECURITY.md for the threat model and disclosure guidance. See docs/authentication.md for the two-layer transport and durable agent-identity design. See docs/standalone.md for running the packaged stdio server and retention janitor from a static PostgreSQL URL. See docs/management-ui.md for mounting the bundled administrative UI with a host-supplied identity dependency.

The optional control plane is provider-neutral. Hosts inject verified principals, including separate workspace-creation and platform-administrator permissions, and may inject an external workspace-entitlement resolver. Platform administrators can inventory workspace metadata and create workspaces, but must explicitly take a workspace role before agent slugs become visible. Workspace administration and explicit agent management never imply content access or decryption. An agent may be explicitly shared read-only with its workspace; individual grants still control editing and deletion. Eligible users create workspaces as owners, invite teammates, and create agent memories. Joined workspaces do not consume their creation quota.

License

Apache License 2.0. See LICENSE.