Metadata-Version: 2.4
Name: agent-memory-os
Version: 0.2.4
Summary: Local-first, MCP-native memory engine for AI agents with RAM cache and context-budgeted recall.
Author: Bastet Agent Team
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agent,local-first,mcp,memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: uvicorn>=0.30; extra == 'api'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: fastapi>=0.115; extra == 'full'
Requires-Dist: mcp>=1.0.0; extra == 'full'
Requires-Dist: numpy>=1.26; extra == 'full'
Requires-Dist: turbovec<1.0,>=0.7; extra == 'full'
Requires-Dist: uvicorn>=0.30; extra == 'full'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: semantic
Requires-Dist: numpy>=1.26; extra == 'semantic'
Requires-Dist: turbovec<1.0,>=0.7; extra == 'semantic'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/yamantaka520/Agent-Memory-OS/main/assets/logo-header.png" alt="Agent Memory OS" width="560">
</p>

A **local-first memory engine for AI agents** — single or multi-agent, with shared and private memories, associative recall, and context-budgeted retrieval. One SQLite file, zero required dependencies, Apache-2.0.

## Why

Agents need durable facts, preferences, procedures, and lessons — but prompt-injected memory blocks are small and overflow fast, and cloud memory platforms add latency, cost, and privacy tradeoffs. AgentMemoryOS separates long-term memory from the context window: memories live in a local database, and each prompt receives only the relevant, budgeted slice.

## Features

- **Local-first, zero-dependency core** — one SQLite file (FTS5), no server required. `pip install` and go.
- **Requester-aware ACL** — every agent profile has private, team, and global memories; visibility is a hard gate enforced before ranking, never a soft score.
- **Dynamic context packs** — token-budgeted, auditable memory selection per prompt (`context_pack_report()` explains every include/exclude decision).
- **Truth arbitration** — duplicate suppression, contradiction detection (`CONFLICT` markers), and reserved budget for core memories.
- **Associative recall (resonance)** — an authoritative `memory_links` graph lets related memories surface even when they share no query terms; traversal is ACL-safe (invisible nodes are untraversable).
- **Hebbian reinforcement** — memories recalled together grow stronger links (`record_recall`, or `auto_reinforce=True` on context packs); unhelpful recalls weaken links and confidence (`helpful=False`).
- **Per-agent recall profiles** — different agent personas weight memory types differently (an engineer leans on `procedure`, a companion on `preference`); profiles persist in the database and re-weight ranking only, never bypassing ACL.
- **Memory lifecycle** — exponential/linear decay, pinning, hard expiry, and a write-side `consolidate()` pass that merges duplicates and synthesizes strongly co-recalled clusters into concept memories.
- **Optional sidecars** — semantic vector candidates (turbovec), MCP server, and a FastAPI Web UI, all behind extras; every candidate rejoins SQLite and passes hard gates before use.

## Install

```bash
pip install 'agent-memory-os[full]'    # recommended: everything (Web UI, MCP, turbovec)
```

Or pick pieces: `agent-memory-os` (core, zero dependencies), `[api]` (Web UI), `[mcp]` (MCP server), `[semantic]` (turbovec vector recall).

Requires Python 3.11+ with SQLite FTS5 (included in standard CPython builds).

After installing, run two commands:

```bash
agent-memory doctor          # verifies FTS5, turbovec, and the other extras
                             # (add --install to auto-install anything missing)
agent-memory token create    # protects the Web UI API with a bearer token
```

The token is stored at `<home>/web_token` (mode 600); `agent-memory-web` picks
it up automatically and the console prompts for it on first use. Manage it
later with `agent-memory token show|rotate|disable`.

## Quickstart

```python
from agent_memory_os import MemoryClient, RecallProfile

client = MemoryClient(home="~/.agent-memory")

# Write memories with ownership and visibility
client.add("User prefers dark mode.", owner="mizuki", type="preference",
           visibility=[])                      # private to owner
client.add("Deploy target is port 8000.", owner="neo", type="environment",
           visibility=["global"])              # visible to every agent

# Requester-aware search: each agent sees only what it may see
hits = client.search("deploy port", requester_agent_id="neo")

# Token-budgeted context pack for the prompt, with reinforcement loop closed
pack = client.context_pack("deploy port", requester_agent_id="neo",
                           max_tokens=1200, auto_reinforce=True)

# Associate memories; linked memories resonate into future recalls
a = client.add("Staging deploy failed with database lock.", visibility=["global"])
b = client.add("Always snapshot before schema changes.", visibility=["global"])
client.link(a.id, b.id, relation="caused_by", weight=0.8)

# Persist an agent persona: soft ranking bias per memory type
client.save_profile(RecallProfile(agent_id="neo",
                                  type_weights={"procedure": 1.5, "note": 0.7}))

# Periodic hygiene: merge duplicates, synthesize concept memories
client.consolidate()
```

## Architecture

```text
query
  -> candidate providers (FTS5 | vector sidecar | resonance graph | fallback)
  -> merge/dedupe by stable memory_id
  -> rejoin authoritative rows from SQLite
  -> ACL hard gate -> expires_at hard gate
  -> scoring (relevance x importance x confidence x freshness x reinforcement)
  -> per-agent profile re-weighting (soft)
  -> truth arbitration + context budget allocation
```

Design invariants:

- The SQLite `memories` table is the single source of truth; FTS/vector indexes are disposable and rebuildable (`rebuild_indexes()`).
- Candidate providers return IDs and scores only — content is always re-read through SQLite behind the ACL and expiry hard gates.
- Association edges (`memory_links`) are authoritative data, survive index rebuilds, decay when unused, and never let an invisible memory bridge two visible ones.

See [SPEC.md](SPEC.md) for the full contract.

## Storage engines: SQLite + turbovec

AgentMemoryOS uses **two storage layers with strictly different authority**:

- **SQLite** (always on) is the single source of truth: memories, links,
  profiles, and the FTS5 lexical index all live in one `memories.db` file.
- **turbovec** (installed with `[full]` / `[semantic]`) is the semantic vector
  engine: an in-memory quantized index that recalls memories by meaning rather
  than keywords. It is deliberately **disposable** — it returns candidate
  `memory_id`s and scores only; every candidate rejoins SQLite and passes the
  ACL/expiry hard gates before its content can be used, and the index can be
  dropped and rebuilt at any time without touching the truth store.

To activate semantic recall, supply an embedding function and wire the
provider in:

```python
from agent_memory_os.providers.turbovec import TurbovecSemanticCandidateProvider

provider = TurbovecSemanticCandidateProvider.from_vectors(
    vectors=embeddings,                      # one row per memory, any embedder
    external_id_by_memory_id=id_mapping,     # stable memory_id -> uint64
    embed_query=embed,                       # str -> vector, same embedder
)
client = MemoryClient(home="~/.agent-memory", candidate_providers=[provider])
```

`agent-memory doctor` confirms the turbovec backend is importable.

## Backup & restore

```bash
agent-memory backup ~/backups/memories-$(date +%F).db   # online, WAL-safe
agent-memory restore ~/backups/memories-2026-07-11.db --force
```

Backups use SQLite's online backup API, so they are consistent even while
agents are writing. Disposable indexes rebuild automatically after a restore.

## Agent integrations

Step-by-step guides for wiring AgentMemoryOS into common agents — click a tile:

<p>
  <a href="docs/integrations/claude-code.md"><img src="assets/integrations/claude-code.svg" alt="Claude Code integration guide" height="56"></a>
  <a href="docs/integrations/codex.md"><img src="assets/integrations/codex.svg" alt="Codex integration guide" height="56"></a>
  <br>
  <a href="docs/integrations/openclaw.md"><img src="assets/integrations/openclaw.svg" alt="OpenClaw integration guide" height="56"></a>
  <a href="docs/integrations/hermes-agent.md"><img src="assets/integrations/hermes-agent.svg" alt="Hermes Agent integration guide" height="56"></a>
</p>

Any MCP-capable agent can use the same pattern: run
`python -m agent_memory_os.mcp_server` as a stdio MCP server pointing at a
shared `AGENT_MEMORY_HOME`.

## MCP server

```bash
pip install 'agent-memory-os[mcp]'
python -m agent_memory_os.mcp_server
```

Tools: `memory_add`, `memory_search`, `memory_context_pack`, `memory_link`, `memory_update`, `memory_recall_feedback`, `memory_consolidate`.

## Web UI

```bash
pip install 'agent-memory-os[api]'
agent-memory-web --host 127.0.0.1 --port 8000 --home ~/.agent-memory-web
```

The console ships with a stats dashboard (scope/type/relation breakdowns, 14-day activity, most-recalled memories), search and recency browsing (memory cards with in-place editing, feedback, links, and delete actions), an interactive association-graph view, a context-pack preview with per-memory decisions, and add/link/consolidate tools — all driven by a global "acting as" identity.

Endpoints: `GET /health`, `GET /api/stats`, `GET /api/dashboard`, `GET|POST /api/memories`, `GET|PATCH|DELETE /api/memories/{id}`, `GET /api/memories/{id}/links`, `GET /api/graph`, `POST /api/links`, `POST /api/recall`, `POST /api/consolidate`, `GET /api/search`, `GET /api/context-pack`.

Search, browse, graph, recall feedback, and context-pack accept `requester_agent_id` and enforce the same ACL hard gates as the SDK. Requests without a requester run in unrestricted admin view — bind to localhost only, or require a bearer token on every API route with `--token <secret>` (or `AGENT_MEMORY_WEB_TOKEN`).

Note: keep the `--home` database on a local disk. Network filesystems (NFS/SMB) can fail SQLite FTS5 schema creation with `database is locked`.

## Development

```bash
pip install -e '.[dev]'
pytest
```

## Status

Alpha (`0.2.x`). The core contracts above are implemented and covered by the test suite; interfaces may still change before `1.0`. See [PROJECT_STATUS.md](PROJECT_STATUS.md) and [PROGRESS.md](PROGRESS.md) for the evidence-backed state of each feature.

## License

[Apache License 2.0](LICENSE)
