Metadata-Version: 2.4
Name: awm
Version: 0.1.0
Summary: A portable, scoped agent memory — hierarchical tenant:user:project scopes where a write lands at exactly one scope, a read includes ancestors by distance, and siblings never leak.
License: Apache-2.0
Project-URL: Homepage, https://github.com/Aitherium/awm
Project-URL: Repository, https://github.com/Aitherium/awm.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# awm

A portable, scoped agent memory. SQLite, no service, no network.

```
platform:*:*               everyone
{tenant}:*:*               one org
{tenant}:{user}:*          one person
{tenant}:{user}:{project}  one piece of work
```

```bash
pip install awm

awm remember --scope acme:alice:orchestrator --key recipe --value "rank 16, lr 2e-5"
awm recall   --scope acme:alice:orchestrator
```

## Two rules, deliberately asymmetric

**A write lands at exactly one scope.** Writing "somewhere in this subtree" is
how a memory becomes visible to a scope its author never considered.

**A read includes ancestors, weighted by distance.** A project query surfaces
the user's preferences and the platform's conventions — that is the point of a
hierarchy — but a platform fact must not outrank a project fact just because it
was written first.

## One property that is security, not tidiness

**Siblings never see each other.** `acme:alice:*` and `acme:bob:*` share an
ancestor and nothing else. The scope check is segment-wise, never a string
prefix, because `"acmecorp:...".startswith("acme")` is `True` — that is one
customer's memory entering another's context, silently, with the answer still
looking like an answer. SQL narrows by an exact computed set, never a `LIKE`.

`platform` is a reserved sentinel tenant meaning "everyone", not an
organisation. Treating it as a literal tenant name made the root of the
hierarchy invisible from every scope — every recall still returned results, just
never the platform's. The self-test carries that case.

## Licence

Apache-2.0.
