agent-filetree-memory-mcp 0.3.0__tar.gz

agent_filetree_memory_mcp-0.3.0/.gitignore

@@ -0,0 +1,22 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+/AGENTS.local.md
+.secrets/
+*.key
+*.pem
+*.p12
+*.pfx
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+/dist/
+/web-ui/node_modules/
+.coverage
+htmlcov/

agent_filetree_memory_mcp-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agent_filetree_memory_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,113 @@
+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).

agent_filetree_memory_mcp-0.3.0/README.md

@@ -0,0 +1,64 @@
+# 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).

agent_filetree_memory_mcp-0.3.0/SECURITY.md

@@ -0,0 +1,19 @@
+# Security
+
+## Supported versions
+
+This project is pre-release. Only the current development version receives security fixes.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Contact the repository owner privately and include the affected version, reproduction steps, impact, and any suggested mitigation. Avoid including real memory content, credentials, signing keys, or database dumps.
+
+## Security model
+
+The trusted host is responsible for authenticating callers and issuing a short-lived capability. The service verifies that capability before any lookup or decryption. A capability binds the outer authenticated principal and invocation to one workspace, immutable agent profile, action set, expiry, and delegation depth. The verifier requires the principal in the signed capability to match the principal established by transport authentication. The principal is the current actor, not part of the durable memory key; the host must issue access only to workspace members authorized for that agent profile.
+
+The database is not a plaintext content index. Paths and directory manifests are encrypted alongside document bodies. Each immutable version uses a fresh AES-256-GCM data-encryption key. A configurable provider wraps that key with the same opaque encryption context used as authenticated data for the document ciphertext.
+
+The design protects against database-only disclosure, accidental cross-scope lookup, moved ciphertext, stale writes, replayed writes, and disclosure through routine audit fields. It does not claim to protect plaintext from a compromised live service process that is authorized to decrypt it.
+
+Deployers remain responsible for network authentication, signing-key custody, encryption-key custody, PostgreSQL access control, backups, observability policy, denial-of-service protection, invoking the packaged retention janitor, and secure deletion guarantees in their storage infrastructure. The request-serving runtime does not contain a scheduler.

agent_filetree_memory_mcp-0.3.0/docs/architecture.md

@@ -0,0 +1,125 @@
+# Architecture
+
+## Goals
+
+The library provides durable, versioned Markdown-like memory without making a filesystem, Git repository, model, or MCP client the authorization boundary. It is designed to be embedded by a trusted agent host or run as a standalone MCP server.
+
+The first release optimizes for five properties:
+
+1. One verified invocation can access exactly one workspace and durable agent profile.
+2. Human-readable paths and content do not appear in plaintext database rows or routine logs.
+3. Writes are concurrency-safe and safely retryable.
+4. Database credentials and key-management implementations remain deployer choices.
+5. Headless MCP tools remain complete when a client does not support MCP Apps.
+
+## Components
+
+```text
+trusted host
+  -> capability verifier
+  -> application service
+       -> PostgreSQL memory store
+            -> encrypted directory manifests
+            -> encrypted immutable document versions
+            -> content-free lifecycle and audit rows
+       -> envelope cipher
+            -> injected DEK provider
+  -> MCP tools
+       -> optional current-capability MCP App
+  -> authenticated management API
+       -> optional workspace and agent control plane
+       -> same application service for memory reads and writes
+  -> bundled management UI
+```
+
+The application layer receives an immutable `VerifiedInvocation`. It never accepts workspace or agent-profile identifiers alongside an operation. Transport adapters resolve the invocation from trusted request context before calling the service.
+
+The durable namespace is `(workspace_id, agent_profile_id)`. `principal_id` is a
+separately authenticated actor recorded in the signed invocation. The optional
+control plane can authorize multiple workspace members to the same profile
+without moving or duplicating its memory. Management permission is independent
+from reader/editor/full content access, and workspace administrators may see
+agent slugs without implicitly gaining decryption access. A deployer may allow
+explicit, audited administrator self-grants or disable them as policy.
+Agent creation atomically provisions an explicit manager row and full-content
+grant for the creator; it does not grant content access to other workspace
+administrators. Platform administration is injected by the host and reveals
+only global workspace metadata until that principal explicitly takes a
+workspace role. Workspace admission and agent-creation policies are signed
+control-plane rows, with an injected provider-neutral resolver for external
+entitlements.
+
+## Database injection
+
+The PostgreSQL adapter supports two construction paths:
+
+- `PostgresRuntime.from_url(...)` creates and owns an async engine for a conventional static database URL.
+- `PostgresRuntime.from_session_factory(...)` receives a ready-to-use async session factory and never creates, refreshes, or disposes host infrastructure.
+
+This is intentionally a session-factory seam rather than a credential-fetcher seam. A hosting platform can rotate credentials, use workload identity, or retrieve secrets inside its own engine without coupling those mechanisms to this package.
+
+## Encrypted virtual tree
+
+Each scope has an opaque root object. Directories are objects whose version content is an encrypted manifest of child display names, opaque object identifiers, and kinds. Documents are objects whose immutable versions contain encrypted UTF-8 Markdown.
+
+Resolving `/projects/example.md` therefore requires:
+
+1. Selecting the opaque root for the already-authorized scope.
+2. Decrypting its manifest and selecting the opaque `projects` object.
+3. Decrypting that directory manifest and selecting the opaque document object.
+4. Loading and decrypting the document's current immutable version.
+
+The plaintext store can route by opaque scope and object identifiers, but it cannot enumerate human-readable paths or titles.
+
+## Encryption
+
+Every object version receives a fresh random 256-bit data-encryption key. AES-256-GCM encrypts the content with canonical associated data containing only format version and opaque scope, object, kind, and version identifiers. A `DekProvider` wraps the data key with the same context.
+
+Rows retain the provider and key identifiers required for rotation. The bundled local keyring provider accepts explicit 32-byte keys and supports reading older keys while writing with one active key. Hosted key-management providers can implement the same small interface.
+
+Moving ciphertext, a wrapped key, or a version row to another object or scope changes the authenticated context and must fail closed.
+
+## Concurrency and retries
+
+Object heads are compare-and-swap values. `write`, `append`, and `delete` take an expected document version. One of two writes against the same version may succeed; the other receives a stable version-conflict error.
+
+Mutations also require an idempotency key. The corresponding request fingerprint and result are encrypted. A retry of the same request returns the original result. Reusing the key for a different request fails without applying either request again.
+
+## Deletion and retention
+
+Delete removes the entry from its encrypted parent manifest and marks the object inaccessible in the same transaction. `purge_after` is an eligibility time, not proof that physical deletion has already run. The package never starts a background scheduler or service lifespan task. A deployer must invoke `agent-filetree-memory-janitor` from cron, a Kubernetes CronJob, or an equivalent host scheduler.
+
+Each janitor invocation selects and locks at most its configured batch limit independently from deleted objects, superseded versions, expired idempotency records, expired rate buckets, and expired audit rows. Repeated invocations drain a larger backlog. Deleting a due object also cascades its versions; `max_versions_per_object` provides a deterministic ceiling on that cascade and on retained ciphertext history. The oldest version is pruned as a new version crosses the ceiling, even when its normal retention time has not arrived.
+
+The janitor requires database access and schema selection, but not capability, idempotency-index, or encryption keys. Backup and replica expiry remain deployer responsibilities and may extend physical recoverability beyond application-table deletion.
+
+## MCP App
+
+The app is a convenience view over the same service layer. Its backend helpers receive paths, content, expected versions, and idempotency keys, but never scope identifiers or a capability token. Every app interaction resolves and reauthorizes the current invocation before lookup or decryption.
+
+Plaintext drafts remain in ephemeral component memory. They are not placed in URLs, browser storage, model-visible context, or the initial widget bootstrap result.
+
+## Management UI
+
+The wheel contains a prebuilt React application plus a provider-neutral
+FastAPI management API. The host injects the authenticated principal, database
+session factory, encryption keys, MCP transport authentication, and policy.
+The UI calls the same application service as MCP; it has no direct database or
+privileged decryption path. FastAPI serves `/api`, `/mcp`, and `/ui` from one
+process, so the frontend and API remain version-matched without requiring Node
+at installation time.
+
+The policy migration does not infer or backfill existing agent managers or
+content grants. Existing agents retain their exact authorization rows; missing
+workspace policy rows default to invite-only admission and administrator-only
+agent creation.
+
+## Deliberate non-goals
+
+- Conversation transcript persistence
+- Automatic memory extraction from prompts or messages
+- Semantic or vector search
+- Automated declassification or content-approval workflows
+- Filesystem mounting or online Git synchronization
+- Binary attachments or collaborative editing
+- A deployer-independent user directory or identity provider