Metadata-Version: 2.5
Name: agent-filetree-memory-mcp
Version: 0.3.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

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

Install the complete standalone package from PyPI:

```shell
pip 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.

## 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).
