Metadata-Version: 2.5
Name: agent-filetree-memory-mcp
Version: 0.4.0
Summary: Encrypted, capability-scoped, versioned Markdown file-tree memory for MCP agents
Project-URL: Homepage, https://github.com/EmilioEsposito/agent-filetree-memory-mcp
Project-URL: Documentation, https://github.com/EmilioEsposito/agent-filetree-memory-mcp/tree/main/docs
Project-URL: Repository, https://github.com/EmilioEsposito/agent-filetree-memory-mcp.git
Project-URL: Issues, https://github.com/EmilioEsposito/agent-filetree-memory-mcp/issues
Author: Emilio Esposito
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,markdown,mcp,memory,postgresql
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Security :: Cryptography
Requires-Python: <3.14,>=3.11
Requires-Dist: cryptography<51,>=49.0.0
Requires-Dist: pyjwt[crypto]<3,>=2.13.0
Requires-Dist: typing-extensions<5,>=4.12; python_version < '3.12'
Provides-Extra: all
Requires-Dist: alembic<2,>=1.18.5; extra == 'all'
Requires-Dist: asyncpg<0.32,>=0.31.0; extra == 'all'
Requires-Dist: fastapi==0.141.1; extra == 'all'
Requires-Dist: fastmcp[apps]==3.4.2; extra == 'all'
Requires-Dist: prefab-ui==0.20.2; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]<2.1,>=2.0.51; extra == 'all'
Requires-Dist: uvicorn==0.52.4; extra == 'all'
Provides-Extra: app
Requires-Dist: fastmcp[apps]==3.4.2; extra == 'app'
Requires-Dist: prefab-ui==0.20.2; extra == 'app'
Provides-Extra: mcp
Requires-Dist: fastmcp==3.4.2; extra == 'mcp'
Provides-Extra: postgres
Requires-Dist: alembic<2,>=1.18.5; extra == 'postgres'
Requires-Dist: asyncpg<0.32,>=0.31.0; extra == 'postgres'
Requires-Dist: sqlalchemy[asyncio]<2.1,>=2.0.51; extra == 'postgres'
Provides-Extra: web
Requires-Dist: alembic<2,>=1.18.5; extra == 'web'
Requires-Dist: asyncpg<0.32,>=0.31.0; extra == 'web'
Requires-Dist: fastapi==0.141.1; extra == 'web'
Requires-Dist: sqlalchemy[asyncio]<2.1,>=2.0.51; extra == 'web'
Requires-Dist: uvicorn==0.52.4; extra == 'web'
Description-Content-Type: text/markdown

# Agent Filetree Memory MCP

[![PyPI version](https://img.shields.io/pypi/v/agent-filetree-memory-mcp.svg)](https://pypi.org/project/agent-filetree-memory-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/agent-filetree-memory-mcp.svg)](https://pypi.org/project/agent-filetree-memory-mcp/)
[![PyPI status](https://img.shields.io/pypi/status/agent-filetree-memory-mcp.svg)](https://pypi.org/project/agent-filetree-memory-mcp/)
[![License](https://img.shields.io/pypi/l/agent-filetree-memory-mcp.svg)](https://spdx.org/licenses/Apache-2.0.html)

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 tool surface is intentionally small: list, read, history-list,
history-read, write, append, and delete. 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.

## Installation

Add the complete package to a uv-managed project:

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

Or install its standalone commands in an isolated environment:

```shell
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](https://github.com/EmilioEsposito/agent-filetree-memory-mcp/blob/main/docs/standalone.md)
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, 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.

## 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](https://github.com/EmilioEsposito/agent-filetree-memory-mcp/blob/main/SECURITY.md) for the threat model and disclosure guidance.
See [docs/authentication.md](https://github.com/EmilioEsposito/agent-filetree-memory-mcp/blob/main/docs/authentication.md) for the two-layer transport
and durable agent-identity design.
See [docs/standalone.md](https://github.com/EmilioEsposito/agent-filetree-memory-mcp/blob/main/docs/standalone.md) for running the packaged stdio
server and retention janitor from a static PostgreSQL URL.
See [docs/management-ui.md](https://github.com/EmilioEsposito/agent-filetree-memory-mcp/blob/main/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 a platform-administrator boolean, 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.

## License

Apache License 2.0. See [LICENSE](https://github.com/EmilioEsposito/agent-filetree-memory-mcp/blob/main/LICENSE).
