agent-memory-os 0.2.3__tar.gz → 0.3.0__tar.gz

agent_memory_os-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with test extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev,api,semantic]' httpx
+      - name: Run test suite
+        run: pytest

agent_memory_os-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run test suite before publishing
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev,api,semantic]' httpx
+          pytest
+      - name: Build distributions
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC) — no token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

{agent_memory_os-0.2.3 → agent_memory_os-0.3.0}/.gitignore

@@ -14,3 +14,5 @@ build/
 .hermes/
 shadow_recall*.jsonl
 *.pyc
+.claude/launch.json
+dist/

{agent_memory_os-0.2.3 → agent_memory_os-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-memory-os
-Version: 0.2.3
+Version: 0.3.0
 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
@@ -16,14 +16,22 @@ 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==0.7.0; extra == 'semantic'
+Requires-Dist: turbovec<1.0,>=0.7; extra == 'semantic'
 Description-Content-Type: text/markdown
 
-# AgentMemoryOS
+<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.
 
@@ -46,14 +54,25 @@ Agents need durable facts, preferences, procedures, and lessons — but prompt-i
 ## Install
 
 ```bash
-pip install agent-memory-os            # core (no dependencies)
-pip install 'agent-memory-os[mcp]'     # + MCP server
-pip install 'agent-memory-os[api]'     # + Web UI
-pip install 'agent-memory-os[semantic]' # + vector candidate sidecar
+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
@@ -108,6 +127,73 @@ Design invariants:
 
 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.
+
+Semantic recall works out of the box:
+
+```python
+client = MemoryClient(home="~/.agent-memory", semantic="auto")
+```
+
+`semantic="auto"` wires in a self-syncing turbovec index over a built-in
+deterministic hashing embedder (no model downloads; typo- and
+morphology-tolerant lexical vectors). The index rebuilds itself whenever the
+memories table changes and degrades silently to lexical + resonance recall
+when the backend isn't installed. For deeper semantics, plug any embedding
+model into `TurbovecSemanticCandidateProvider.from_vectors(...)` with your
+own `embed_query`. `agent-memory doctor` confirms the backend is importable.
+
+## Memory lifecycle & retention
+
+```bash
+agent-memory retention               # archive expired + memories idle 4+ half-lives
+agent-memory retention --half-lives 0   # expired only
+agent-memory check                   # SQLite + FTS + link-graph integrity
+```
+
+Archived memories leave recall entirely but stay restorable (Web UI → Tools →
+Retention & archive, or `POST /api/archive/{id}/restore`). Pinned and
+authority-track memories are never archived by decay. Databases self-migrate
+through a versioned, forward-only migration table (`agent-memory check`
+reports the schema version).
+
+## 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

{agent_memory_os-0.2.3 → agent_memory_os-0.3.0}/README.md

@@ -1,4 +1,6 @@
-# AgentMemoryOS
+<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.
 
@@ -21,14 +23,25 @@ Agents need durable facts, preferences, procedures, and lessons — but prompt-i
 ## Install
 
 ```bash
-pip install agent-memory-os            # core (no dependencies)
-pip install 'agent-memory-os[mcp]'     # + MCP server
-pip install 'agent-memory-os[api]'     # + Web UI
-pip install 'agent-memory-os[semantic]' # + vector candidate sidecar
+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
@@ -83,6 +96,73 @@ Design invariants:
 
 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.
+
+Semantic recall works out of the box:
+
+```python
+client = MemoryClient(home="~/.agent-memory", semantic="auto")
+```
+
+`semantic="auto"` wires in a self-syncing turbovec index over a built-in
+deterministic hashing embedder (no model downloads; typo- and
+morphology-tolerant lexical vectors). The index rebuilds itself whenever the
+memories table changes and degrades silently to lexical + resonance recall
+when the backend isn't installed. For deeper semantics, plug any embedding
+model into `TurbovecSemanticCandidateProvider.from_vectors(...)` with your
+own `embed_query`. `agent-memory doctor` confirms the backend is importable.
+
+## Memory lifecycle & retention
+
+```bash
+agent-memory retention               # archive expired + memories idle 4+ half-lives
+agent-memory retention --half-lives 0   # expired only
+agent-memory check                   # SQLite + FTS + link-graph integrity
+```
+
+Archived memories leave recall entirely but stay restorable (Web UI → Tools →
+Retention & archive, or `POST /api/archive/{id}/restore`). Pinned and
+authority-track memories are never archived by decay. Databases self-migrate
+through a versioned, forward-only migration table (`agent-memory check`
+reports the schema version).
+
+## 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

agent_memory_os-0.3.0/assets/README.md

@@ -0,0 +1,19 @@
+# Assets
+
+Canonical logo: `agent-memory-os-logo-integrated-v2.png` (wordmark, 1981×793).
+
+Derived variants (regenerate from the canonical file when it changes):
+
+- `logo-header.png` — 960px optimized banner; README header on GitHub /
+  GitLab and PyPI (referenced by absolute raw.githubusercontent URL).
+- `logo-icon-512.png` — square A+cat glyph, transparent background; also
+  copied to the repo root as `logo.png`, which GitLab auto-uses as the
+  project avatar.
+- `logo-icon-128.png` — small icon; embedded base64 in the Web UI as the
+  brand mark and favicon (`src/agent_memory_os/web_ui.py`).
+- `integrations/` — clickable integration badges used by the root README.
+  Original wordmark tiles, no third-party trademark artwork.
+
+GitHub has no repo avatar API: set Settings → Social preview manually with
+`logo-header.png` if wanted. Other logo files (`-ai-v1`, plain, wordmark)
+are design-iteration history.

agent_memory_os-0.3.0/assets/agent-memory-os-logo.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
+  <title id="title">Agent Memory OS logo</title>
+  <desc id="desc">A white geometric letter A on a purple field with a memory-profile silhouette formed in negative space.</desc>
+  <rect width="512" height="512" rx="72" fill="#4B2E83"/>
+  <path
+    fill="#FFFFFF"
+    fill-rule="evenodd"
+    d="M72 448 207 64h98l135 384H333l-22-76H201l-22 76H72Zm150-148h68l-34-116-34 116Z"
+  />
+  <path
+    fill="#4B2E83"
+    d="M201 448c0-70 9-132 28-186 18-53 46-102 83-147 8-10 23-7 27 6l14 48c8-2 17-3 27-2 32 3 58 27 63 59 2 13 8 20 19 24 17 6 27 23 25 42-3 35-29 59-69 68-30 7-51 18-57 36-4 13 1 24 15 33 27 17 49 41 65 72 8 15-3 33-20 33H201v-86Z"
+  />
+  <circle cx="295" cy="225" r="9" fill="#FFFFFF"/>
+  <circle cx="326" cy="203" r="7" fill="#FFFFFF"/>
+  <circle cx="359" cy="214" r="8" fill="#FFFFFF"/>
+  <path d="M302 221 321 207M333 205l19 7" stroke="#FFFFFF" stroke-width="7" stroke-linecap="round"/>
+</svg>

agent_memory_os-0.3.0/assets/agent-memory-os-wordmark.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 360" role="img" aria-labelledby="title desc">
+  <title id="title">Agent Memory OS wordmark</title>
+  <desc id="desc">Agent Memory OS wordmark with the negative-space A icon and text.</desc>
+  <rect width="360" height="360" rx="48" fill="#4B2E83"/>
+  <path
+    fill="#FFFFFF"
+    fill-rule="evenodd"
+    d="M51 315 146 45h69l95 270h-75l-15-54h-78l-15 54H51Zm105-104h48l-24-82-24 82Z"
+  />
+  <path
+    fill="#4B2E83"
+    d="M142 315c0-49 7-93 20-131 13-37 32-72 58-104 6-7 16-5 19 4l10 34c6-2 12-2 19-1 23 2 41 19 45 42 1 9 5 14 13 17 12 4 19 16 18 30-2 24-21 41-49 47-21 5-36 13-40 25-3 9 1 17 11 23 19 12 35 29 46 51 5 11-2 23-15 23H142v-60Z"
+  />
+  <circle cx="209" cy="158" r="6" fill="#FFFFFF"/>
+  <circle cx="230" cy="143" r="5" fill="#FFFFFF"/>
+  <circle cx="253" cy="151" r="6" fill="#FFFFFF"/>
+  <path d="m214 155 13-10m9-1 14 5" stroke="#FFFFFF" stroke-width="5" stroke-linecap="round"/>
+  <text
+    x="430"
+    y="163"
+    fill="#211A2E"
+    font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+    font-size="78"
+    font-weight="800"
+    letter-spacing="0"
+  >Agent Memory OS</text>
+  <text
+    x="433"
+    y="227"
+    fill="#685B7F"
+    font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
+    font-size="30"
+    font-weight="600"
+    letter-spacing="0"
+  >Local-first recall for AI agents</text>
+</svg>

agent_memory_os-0.3.0/assets/integrations/claude-code.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="220" height="64" viewBox="0 0 220 64" role="img" aria-label="Claude Code integration guide">
+  <rect x="1" y="1" width="218" height="62" rx="14" fill="#1d1a17" stroke="#3d342c"/>
+  <circle cx="32" cy="32" r="17" fill="#d97757"/>
+  <g transform="translate(32 32)" stroke="#1d1a17" stroke-width="3.4" stroke-linecap="round">
+    <line x1="0" y1="-10" x2="0" y2="10"/>
+    <line x1="-8.7" y1="-5" x2="8.7" y2="5"/>
+    <line x1="-8.7" y1="5" x2="8.7" y2="-5"/>
+  </g>
+  <text x="60" y="30" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="16" font-weight="700" fill="#f3ede7">Claude Code</text>
+  <text x="60" y="47" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="11" fill="#a89e93">integration guide →</text>
+</svg>

agent_memory_os-0.3.0/assets/integrations/codex.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="220" height="64" viewBox="0 0 220 64" role="img" aria-label="Codex integration guide">
+  <rect x="1" y="1" width="218" height="62" rx="14" fill="#101314" stroke="#2c3436"/>
+  <circle cx="32" cy="32" r="17" fill="#e8eceb"/>
+  <g stroke="#101314" stroke-width="3.2" stroke-linecap="round" fill="none">
+    <polyline points="24,26 31,32 24,38"/>
+    <line x1="35" y1="38" x2="42" y2="38"/>
+  </g>
+  <text x="60" y="30" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="16" font-weight="700" fill="#eef2f1">Codex</text>
+  <text x="60" y="47" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="11" fill="#96a2a0">integration guide →</text>
+</svg>

agent_memory_os-0.3.0/assets/integrations/hermes-agent.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="220" height="64" viewBox="0 0 220 64" role="img" aria-label="Hermes Agent integration guide">
+  <rect x="1" y="1" width="218" height="62" rx="14" fill="#141126" stroke="#312a55"/>
+  <circle cx="32" cy="32" r="17" fill="#8b6ef6"/>
+  <g stroke="#141126" stroke-width="3" stroke-linecap="round" fill="none">
+    <path d="M 22 38 Q 30 36 34 30 Q 36 26 34 23"/>
+    <path d="M 26 40 Q 34 39 39 33"/>
+    <path d="M 31 42 Q 38 42 43 37"/>
+  </g>
+  <text x="60" y="30" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="16" font-weight="700" fill="#efecfb">Hermes Agent</text>
+  <text x="60" y="47" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="11" fill="#a49bce">integration guide →</text>
+</svg>

agent_memory_os-0.3.0/assets/integrations/openclaw.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="220" height="64" viewBox="0 0 220 64" role="img" aria-label="OpenClaw integration guide">
+  <rect x="1" y="1" width="218" height="62" rx="14" fill="#1b1210" stroke="#43261f"/>
+  <circle cx="32" cy="32" r="17" fill="#e0563a"/>
+  <g stroke="#1b1210" stroke-width="3.2" stroke-linecap="round" fill="none">
+    <path d="M 24 40 Q 24 24 33 22"/>
+    <path d="M 29 41 Q 30 29 37 26"/>
+    <path d="M 35 42 Q 37 33 42 31"/>
+  </g>
+  <text x="60" y="30" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="16" font-weight="700" fill="#f6ece8">OpenClaw</text>
+  <text x="60" y="47" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="11" fill="#b39a91">integration guide →</text>
+</svg>

{agent_memory_os-0.2.3 → agent_memory_os-0.3.0}/docs/AgentMemoryOS_README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src="../assets/logo-header.png" alt="Agent Memory OS" width="480"></p>
+
 # AgentMemoryOS
 
 ## 🚀 Project Overview

agent_memory_os-0.3.0/docs/Roadmap.md

@@ -0,0 +1,76 @@
+# AgentMemoryOS Roadmap
+
+Last updated: 2026-07-11
+
+Governance rules:
+
+1. A milestone is "done" only when its features are merged, tested, and
+   evidenced in this repository. Production claims (canary percentages,
+   default-backend status, traffic switches) belong in `PROJECT_STATUS.md`
+   with evidence, never here.
+2. **Web console parity is part of Done**: every engine feature that changes
+   what users can inspect or control (new memory fields, new operations, new
+   retrieval behavior) ships with matching Web UI support in the same
+   milestone — the console must never lag the engine.
+
+## Shipped — v0.2.3 (current release)
+
+- SQLite + FTS5 source of truth; requester-aware ACL and expiry hard gates
+- Truth arbitration, context budget packs with auditable decisions
+- Memory association layer: authoritative `memory_links`, resonance recall
+  (ACL-safe traversal), link decay, hub damping, supersedes demotion
+- Recall loop: Hebbian reinforcement, negative feedback, auto-reinforce packs
+- Per-agent `RecallProfile` personas (persisted, auto-applied)
+- Write-side consolidation (duplicate merge + concept synthesis)
+- turbovec semantic candidate sidecar (validation-gated, disposable)
+- Web console: dashboard, search/browse/edit, association graph, tools,
+  bearer-token auth; MCP server (9 tools); token/doctor/backup CLI
+- CI (3 Python versions) and Trusted-Publishing release workflow
+
+## v0.3 — Robust persistent memory (in progress)
+
+Goal: a memory you can trust with years of an agent's life.
+
+1. **Durability operations** — `agent-memory backup/restore` (shipped),
+   scheduled snapshot rotation, integrity check command
+   (`PRAGMA integrity_check` + row-count/id invariants).
+2. **Schema migrations** — versioned migration table and forward-only
+   migration runner, replacing ad-hoc `ALTER TABLE` checks; downgrade
+   verification stays a release gate.
+3. **Embedding pipeline** — optional background indexer that keeps a turbovec
+   index in sync with the memories table (pluggable embedder), so semantic
+   recall works out of the box instead of requiring hand-wired vectors.
+4. **Retention policies** — per-scope/type archival rules: expired and
+   decayed-out memories move to a cold archive table (excluded from recall,
+   restorable) instead of deletion-only lifecycle.
+5. **Hermes activation evidence** — shadow comparison logs, golden recall at
+   target, importer idempotency; gates in `PROJECT_STATUS.md`.
+
+## v0.4 — Dynamic context orchestration (design + prototypes)
+
+Goal: the memory system decides *what enters the context window, when* —
+not just what exists.
+
+1. **Session working memory** — `ContextSnapshot` offload/reload (prototype
+   shipped, exposed via MCP): agents park working state mid-session and
+   resume across context-window resets; add snapshot retention and diffing.
+2. **Budget-aware orchestration** — one call that splits a token budget
+   across bedrock memories, task-relevant recall, resonance neighbors, and
+   session snapshots, with per-bucket reserves (extends the v0.2.2
+   arbitration allocator).
+3. **Proactive recall** — type-aware triggers: procedures surface when a task
+   type is detected, warnings surface before matching risky actions, not
+   only on lexical/semantic query match.
+4. **Mid-task recall loop** — MCP affordances for iterative deepening
+   (initial pack → follow-up queries with dedup against what the agent
+   already saw this session).
+5. **Resonance maturation** — LLM-assisted triplet extraction at
+   consolidation time replacing regex ERA; graph-quality metrics
+   (hub distribution, orphan rate) on the dashboard.
+
+## Later / research
+
+- Cross-agent memory negotiation: explicit share/de-identify flows with audit
+  trail (private → team without copy-paste)
+- Federated multi-host sync with conflict resolution
+- Forgetting curves tuned from recall-feedback telemetry

agent_memory_os-0.3.0/docs/integrations/claude-code.md

@@ -0,0 +1,67 @@
+# Using AgentMemoryOS with Claude Code
+
+Claude Code speaks MCP natively, so the memory engine plugs in as a stdio MCP
+server — no glue code required.
+
+## 1. Install
+
+```bash
+pip install 'agent-memory-os[full]'
+agent-memory doctor
+```
+
+## 2. Register the MCP server
+
+Project-scoped (recommended — the whole team gets it via `.mcp.json`):
+
+```bash
+claude mcp add agent-memory --scope project \
+  --env AGENT_MEMORY_HOME=$HOME/.agent-memory \
+  -- python -m agent_memory_os.mcp_server
+```
+
+Or user-scoped (`--scope user`) to share one memory home across all projects.
+
+Equivalent `.mcp.json` entry if you prefer editing the file directly:
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "python",
+      "args": ["-m", "agent_memory_os.mcp_server"],
+      "env": { "AGENT_MEMORY_HOME": "~/.agent-memory" }
+    }
+  }
+}
+```
+
+## 3. Teach Claude when to use it
+
+Add a short section to your `CLAUDE.md` so the model reaches for memory at the
+right moments:
+
+```markdown
+## Memory
+- At the start of a task, call `memory_context_pack` with a short description
+  of the task to recall relevant facts, procedures, and warnings.
+- When you learn a durable fact, preference, decision, or lesson, save it with
+  `memory_add` (owner = this agent's id; use visibility ["global"] for
+  team-wide knowledge, [] for private).
+- When recalled memories were helpful or misleading, report it with
+  `memory_recall_feedback` so ranking improves.
+```
+
+## 4. Available tools
+
+`memory_add`, `memory_search`, `memory_context_pack`, `memory_link`,
+`memory_update`, `memory_recall_feedback`, `memory_consolidate`,
+`memory_offload_context`, `memory_reload_context`.
+
+## Tips
+
+- Give each agent persona a stable `owner` id so private/team/global
+  visibility boundaries mean something.
+- Keep `AGENT_MEMORY_HOME` on a local disk (not NFS/SMB).
+- Run the Web console (`agent-memory-web`) beside it to inspect what the
+  agent remembers, browse the association graph, and prune.