From c52868095db6bb9aaa4eb86bec15a46681324f33 Mon Sep 17 00:00:00 2001 From: Andrew_Moryakov Date: Thu, 1 Oct 2026 11:50:47 +0300 Subject: [PATCH 1/2] docs: README depth pass - describe the whole runtime for newcomers and advanced users (EN + RU) --- README.md | 439 +++++++++++++++++++++++++++++++++++++++++++-------- README.ru.md | 437 ++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 739 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index 895843b..ce612c4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

AgentMemory: several AI tool robots and a script read and write notes through one shared memory runtime, with swappable storage behind it

AgentMemory

-

One shared local memory runtime for your AI tools and scripts — CLI, HTTP API and MCP on top of a swappable memory backend such as mem0.

+

One shared local memory runtime for your AI tools and scripts: a stable set of memory operations over CLI, HTTP API and MCP (local or remote), swappable storage providers such as mem0, built-in diagnostics, client wiring, a web console and a provider certification harness.

License: MIT Python 3.11+ @@ -16,7 +16,106 @@ agentmemory configure --provider localjson # no API keys needed agentmemory start-api # one local runtime, several client surfaces ``` -AgentMemory is a shared local memory runtime for AI clients and agents. It sits above a memory backend such as `mem0` and exposes one stable surface through CLI, HTTP API, and MCP — so what one tool saves, another can recall. It is currently a **public alpha**; see [Current Status](#current-status) and [Current Limitations](#current-limitations) before you depend on it. +AgentMemory is a shared local memory runtime for AI clients and agents. It sits above a memory backend (a *provider*: `mem0`, a built-in JSON store, and two experimental adapters) and exposes **one stable set of 14 memory operations** through a CLI, a local HTTP API and an MCP server, so what one tool saves, another can recall. Around that core it adds: an owner-process transport for backends that cannot be opened by many processes at once; one-command wiring into ten AI clients and editors; a remote MCP endpoint with bearer-token and OAuth 2.1 (Dynamic Client Registration) support; JSONL export/import; opt-in memory semantics (dedup, TTL, stale warnings, a read-only conflict check); a `doctor` that explains what is wrong; a browser console; metrics; Docker deployment files; and a provider certification harness for adding new backends. + +It is a **public alpha** (version 0.1.0, local-first, not hardened for hostile multi-tenant or open-network use). See [Current Status](#current-status) and [Current Limitations](#current-limitations) before you depend on it. + +**Contents:** [In plain words](#in-plain-words) · [What's inside](#whats-inside) · [How it works](#how-it-works) · [Quick start](#quickstart) · [Concepts](#concepts) · [Surfaces](#surfaces) · [Providers](#providers) · [Client wiring](#client-wiring) · [Remote MCP](#remote-mcp-connectors-claudeai-chatgpt) · [Security](#security-and-identity) · [Memory semantics](#memory-semantics) · [Data portability](#export-import-and-hygiene) · [Web console](#browser-ui) · [Operations](#operations-and-deployment) · [Reference](#reference) · [Troubleshooting](#troubleshooting) · [Status](#current-status) · [Limitations](#current-limitations) · [Docs map](#documentation-map) + +## In plain words + +### The problem + +Every AI tool you use keeps its own notes, or none at all. A coding agent learns your preferences, and the next tool, a script or a different agent starts from zero. Memory backends such as `mem0` solve *storing and ranking* memories, but each has its own SDK, its own record shapes and its own quirks: some use local files that only one process may open, some need API keys, some are not reachable from a hosted AI client at all. Without a shared layer, every tool re-implements the integration and behaves differently. + +### Who it is for + +People who run several AI clients or agents (Claude Code, Codex, Gemini CLI, Cursor and similar), plus scripts, and want them to share one memory on their own machine; people who want to expose that memory to hosted clients such as Claude.ai or ChatGPT custom connectors; and developers who want to put another memory backend behind the same contract. + +### What you get + +- **One memory, many clients.** The same operations (add, search, list, get, update, delete, scopes, export/import, reconcile, health) are available from the CLI, an HTTP API and MCP tools, with the same validation and the same typed errors. +- **A backend you can swap.** Providers sit behind one contract with normalized records and declared capabilities. Start with the zero-dependency `localjson` provider; switch to `mem0` for semantic retrieval. +- **A runtime that copes with fragile backends.** When a backend must be opened by one process only, one *owner* process runs it and everything else proxies through it. +- **Setup help.** `connect-clients` wires AgentMemory into detected clients (Windows-first), `doctor` and `doctor-clients` say what is wrong, named profiles separate environments. +- **Remote access when you want it.** MCP over HTTP at `/mcp`, bearer token or OAuth 2.1 with Dynamic Client Registration, rate limits and a request-size cap. +- **Ways to look and to move.** A browser console to inspect and edit memories, JSONL export/import, Prometheus-format metrics, Docker files. + +### What it is not + +- Not a memory *policy* engine. It does not decide what is worth remembering or how long it should live; callers do. TTL exists only as opt-in, caller-supplied metadata ([Runtime boundaries](docs/RUNTIME_BOUNDARIES.md)). +- Not a memory engine itself. The storage and retrieval quality come from the provider you choose. +- Not an authentication system for people. It has no user login; the OAuth authorize step identifies the *client*, not a person. The optional identity binding is **not tenant isolation** ([details](#security-and-identity)). +- Not hardened for hostile multi-tenant or open-network exposure ([SECURITY.md](SECURITY.md)). +- Not needed if one Python application owns its memory directly and you do not need MCP or HTTP access: direct `mem0` integration is usually simpler. + +### Glossary + +| Term | Meaning here | +|---|---| +| **Provider** | A memory backend adapter (`mem0`, `localjson`, `claude_memory`, `mempalace`) behind the shared contract. | +| **Provider contract** | The stable boundary: normalized `MemoryRecord` / `DeleteResult`, page shapes, declared capabilities, runtime policy and typed errors. | +| **Operation** | One of 14 shared actions (for example `add`, `search`) defined once in the operation registry and exposed by every surface. | +| **Surface** | A way to reach the operations: CLI, HTTP API, MCP server, interactive shell, browser UI. | +| **Scope** | The `user_id` / `agent_id` / `run_id` a memory belongs to. Some providers (`mem0`) require a scope for list and search. | +| **Owner process** | The single local API process that owns a backend which cannot be opened concurrently; other clients proxy through it. | +| **MCP** | Model Context Protocol, the way AI clients call tools such as `memory_search`. | +| **DCR** | OAuth Dynamic Client Registration (RFC 7591): a hosted client registers itself, so no client id has to be issued by hand. | +| **Certification** | A check that a provider honours the contract (reusable harness plus `provider-certify`). | + +## What's inside + +Status labels: unlabeled = implemented in this repository; **experimental** = implemented but not certified; **opt-in** = implemented, off unless you enable it; **planned** = design or roadmap only. + +### One runtime, three main surfaces + +- **Operation registry.** Fourteen operations are defined once and dispatched by CLI, HTTP and MCP through the same validation, typed-error shaping and identity check. → [Concepts](#concepts) +- **CLI.** `agentmemory` for install, configure, diagnostics, API control, client wiring, profiles, export/import and certification; `agentmemory.ops_cli` for data operations. Run with no arguments it opens an interactive shell with onboarding and slash commands. → [Surfaces](#surfaces) +- **HTTP API.** A local stdlib-based server with memory routes, admin routes, `/health`, `/metrics` and `/mcp`. → [HTTP API](#http-api) +- **MCP server.** A stdio server exposing the 14 `memory_*` tools, and the same tools over HTTP at `POST /mcp`; tool arguments are validated against each tool's input schema. → [MCP](#mcp) + +### Providers + +- **`mem0`.** The main semantic provider: semantic search with rerank, filters, update/delete, embedded storage, owner-process transport. Needs an OpenRouter key. → [Providers](#providers) +- **`localjson`.** Built-in, no API keys: text search, pagination, an inspectable JSON file. Meant for tests and demos. → [Providers](#providers) +- **`claude_memory`** (**experimental**). A conservative file-backed adapter over Claude Code memory surfaces; no update or delete. → [Providers](#providers) +- **`mempalace`** (**experimental**). A local semantic provider over an AgentMemory-owned MemPalace collection; no update. → [Providers](#providers) + +### Connecting clients + +- **`connect-clients`.** Detects and configures Codex, Claude Code, Claude Desktop, Gemini CLI, Qwen CLI, Cursor, VS Code / Copilot, Roo Code, KiloCode and Cline; `disconnect-clients`, `status-clients` and `doctor-clients` (json / table / compact output) complete the loop. Windows-first. → [Client wiring](#client-wiring) +- **Snippets and launchers.** `agentmemory snippets` prints Claude Code and Gemini CLI configuration; PowerShell and POSIX launchers sit at the repository root. → [Root entry points](#root-entry-points) + +### Remote access and security + +- **Remote MCP.** `POST /mcp` with a pre-shared bearer token and/or OAuth 2.1 (authorization code, refresh-token rotation, discovery documents, Dynamic Client Registration). → [Remote MCP](#remote-mcp-connectors-claudeai-chatgpt) +- **Guards.** Per-credential rate limit, per-IP limit on registration, request body cap, the browser UI can be switched off. → [Security](#security-and-identity) +- **Identity binding** (**opt-in**). Bind a credential to one `user_id` so it cannot name another scope. Not tenant isolation. → [Security](#security-and-identity) + +### Memory semantics (all caller-controlled) + +- **`infer`** (default off). Memories are stored verbatim unless the caller asks the provider's LLM to extract or rewrite them; rewrites are observable. → [Memory semantics](#memory-semantics) +- **Dedup on add** (**opt-in**), **TTL expiry** (**opt-in**, off by default), **stale-after warnings** on search results, and a read-only **conflict check** (`reconcile`). → [Memory semantics](#memory-semantics) +- **Scope inventory.** `list-scopes` reads an AgentMemory-owned registry; `rebuild-scope-registry` repairs it. → [Concepts](#concepts) + +### Data, diagnostics and operations + +- **Export / import.** Provider-neutral JSONL. → [Export, import and hygiene](#export-import-and-hygiene) +- **`doctor`, profiles and guidance.** Checks venv, config, keys and health; named profiles such as `default` and `staging`; provider-specific guidance. → [Profiles and doctor](#profiles-and-doctor) +- **Metrics.** In-process counters and latency, with a Prometheus text endpoint. → [Metrics](#metrics) +- **Docker and deployment files.** A Dockerfile that also builds the web console, compose files and a Traefik-fronted deployment guide. → [Operations and deployment](#operations-and-deployment) + +### Web console + +- **Browser UI.** Memory explorer (table and timeline), detail inspector, edit, pin, delete, add, bulk selection, scope filters, a command palette and keyboard shortcuts, a runtime status strip. Needs a one-time front-end build when you run from source. → [Browser UI](#browser-ui) + +### Building and certifying providers + +- **Adapter rules and contract harness.** A reusable test harness every provider subclasses; `provider-certify` and `provider-certify-ci` report and gate certification status. → [Provider certification](#provider-certification) + +### Not built yet + +Planned or proposed only, not in the code: a document-oriented provider backed by git and Markdown, more providers (for example Zep, Hindsight, Cognee, Graphiti), memory review and collaboration phases of the console, a soft-delete window for the TTL sweeper, a sanity guard for TTL values, a `memory_type` filter, cursor pagination for `mem0`, and an identity story for DCR-created OAuth clients. See [ROADMAP](docs/planning/ROADMAP.md), [BACKLOG](docs/planning/BACKLOG.md) and [Future Memory Providers](docs/future-memory-providers/README.md). ## Why AgentMemory? @@ -27,7 +126,7 @@ Most memory systems solve the backend problem: storing, retrieving, and ranking - **If** you want a stable contract above backend-specific quirks, **then** providers sit behind one provider contract with normalized records and typed errors. - **If** you also want to look at what was remembered, **then** the local API serves a browser UI for inspection and editing, and `doctor` commands explain what is wrong. -The distinction in one line: `mem0` is a memory engine; `AgentMemory` is a memory runtime layer — and it is *not* the layer that decides what should be remembered temporarily or permanently. +The distinction in one line: `mem0` is a memory engine; `AgentMemory` is a memory runtime layer, and it is *not* the layer that decides what should be remembered temporarily or permanently. **Who it is not for.** You probably do not need AgentMemory if one Python application owns memory directly, direct provider integration is already clean, you do not need MCP or HTTP access, and you do not need several tools to share one runtime. In that case, direct `mem0` integration is usually simpler. @@ -41,17 +140,6 @@ Fuller explanations: More concrete scenarios: [Use Cases](docs/USE_CASES.md), [Shared Runtime Demo](examples/shared-runtime-demo.md), [MCP Demo](examples/mcp-demo.md). -## Features - -- **One runtime, three surfaces** — CLI, local HTTP API, and MCP all go through the same shared operations. -- **Swappable providers** — `mem0` (main semantic path), `localjson` (built-in test/demo provider), `claude_memory` (conservative file-backed adapter for Claude Code memory surfaces), and `mempalace` (experimental local semantic provider). -- **Client wiring** — `connect-clients` auto-connects AgentMemory to detected AI clients and editors; `status-clients` and `doctor-clients` check the result. Windows-first. -- **Browser UI** — runtime overview, memory explorer, edit, pin and delete, client status. -- **Remote MCP connectors** — MCP over HTTP at `POST /mcp` with OAuth 2.1 and Dynamic Client Registration, for hosted clients such as Claude.ai and ChatGPT custom connectors. -- **Diagnostics built in** — `doctor` checks venv, config, key availability and health; capability-aware guidance is part of the product surface. -- **Optional lifecycle semantics** — TTL expiry when the caller chooses to use it. -- **Provider certification** — providers are checked against one shared contract (`provider-certify`). - ## How it works

@@ -147,6 +235,12 @@ What success looks like: - `start-api` starts cleanly with the configured provider - you can rerun `.\.venv\Scripts\python.exe .\examples\http_python_roundtrip.py` +### Next steps + +- Connect your AI clients: `agentmemory connect-clients`, then `agentmemory status-clients --compact` ([Client wiring](#client-wiring)). +- Look at what was stored in the browser console ([Browser UI](#browser-ui); from source it needs a one-time `npm install && npm run build` in `web/`). +- Run the MCP self-test: `agentmemory mcp-smoke`. + ### Shared Runtime Demo The canonical onboarding story is: @@ -176,6 +270,8 @@ If the quickstart does not work immediately, check these first: - If the API port is already busy, `start-api` should choose a free port; rerun the roundtrip script only after the printed API URL appears. - If the `mem0` path fails, go back to `localjson` first. The first evaluation path should not depend on external API keys or semantic-provider setup. +More in [Troubleshooting](#troubleshooting). + ## Architecture Snapshot ```mermaid @@ -199,30 +295,34 @@ More detail: - [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md) - [Future Memory Providers](docs/future-memory-providers/README.md) -## Current Status +## Concepts -- `public alpha` -- local-first product -- runtime core works on Windows, Linux, and expected macOS paths -- Windows-first client integration workflow -- `mem0` is the main semantic provider -- `localjson` is the built-in testing and demo provider -- `claude_memory` is the conservative file-backed adapter for Claude Code memory surfaces -- `mempalace` is the experimental local semantic provider backed by an AgentMemory-owned MemPalace collection -- provider contract, operation registry, transport adapters, and runtime policy are implemented -- diagnostics and scope discovery are part of the current product surface +### Scopes and records -## Current Limitations +A memory belongs to a **scope**: a `user_id`, an `agent_id`, a `run_id`, or a combination. Providers declare whether a scope is required (`mem0` requires one for list and search; `localjson` does not). Every provider returns the same normalized `MemoryRecord` (`id`, text, `metadata` always a dict, `provider` always populated, optional provider-specific payload only under `raw`), so clients never see backend-native shapes. Unsupported options fail with typed errors (`ProviderCapabilityError`, `ProviderScopeRequiredError`, `MemoryNotFoundError`, `ProviderUnavailableError`, `ProviderValidationError`, `ProviderConfigurationError`, and `ProviderIdentityError` for the identity check) rather than leaking backend exceptions. -AgentMemory is usable as a local shared-memory runtime, but it is still a public alpha. The current risk/bug index lives in [Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md). +AgentMemory keeps its own **scope registry** (an AgentMemory-owned inventory that `list-scopes` reads). Primary provider storage stays the source of truth; a failed registry sync marks the provider degraded instead of faking a failed write, and `agentmemory rebuild-scope-registry` repairs it. -Important current limitations: +### The 14 operations -- TTL exists as optional expiry support. It is caller-controlled metadata, not automatic short-term/long-term classification. Providers with degraded scope registry sync may require `rebuild-scope-registry` before TTL sweeps can be considered complete. -- `mem0` uses the safe single-page fallback for pagination until a backend-safe cursor strategy is implemented. -- Compose v2 external-network drift is mitigated by `deploy/redeploy.sh`, but the upstream root cause remains outside this repo. +Defined once in the operation registry ([operations.py](agentmemory/runtime/operations.py)) and exposed as MCP tools with the `memory_` prefix: + +| Operation | MCP tool | What it does | +|---|---|---| +| `health` | `memory_health` | Runtime and provider information | +| `add` | `memory_add` | Store a memory (verbatim by default; `infer`, `dedup`, TTL metadata are opt-in) | +| `get` / `update` / `delete` | `memory_get` / `memory_update` / `memory_delete` | Work by record id; availability depends on provider capabilities | +| `search` / `search_page` | `memory_search` / `memory_search_page` | Semantic or text search, optionally one cursor page | +| `list` / `list_page` | `memory_list` / `memory_list_page` | Browse records in a scope | +| `list_scopes` / `list_scopes_page` | `memory_list_scopes` / `memory_list_scopes_page` | Known user, agent and run scopes | +| `export` / `import` | `memory_export` / `memory_import` | Provider-neutral JSONL | +| `reconcile` | `memory_reconcile` | Read-only check for likely conflicting memories | -## Key Design Choice For Mem0 +### Layers + +The runtime is layered: clients, then surfaces (CLI, HTTP, stdio MCP, interactive shell, browser UI), then the runtime core (registry, adapters, validation, error shaping, routing, diagnostics), then the provider contract, then provider adapters, then backend storage. Backend-specific behavior terminates at the provider boundary. See [Architecture](docs/ARCHITECTURE.md) and [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md). + +### Key Design Choice For Mem0 `mem0` uses local embedded storage in this project, and local embedded backends can have process and lock constraints. @@ -234,7 +334,49 @@ AgentMemory handles that by giving the provider an explicit runtime transport po This is one of the clearest examples of why a memory runtime layer can be useful even when the backend is still `mem0`. -## Main Commands +In practice: `mem0` declares the `owner_process_proxy` policy. When a CLI command or the stdio MCP server needs the backend, it makes sure the local API is running (starting it under a cross-process lock if necessary) and forwards the call over HTTP, including the API token when one is configured. Providers that declare `direct` transport (`localjson`, `claude_memory`, `mempalace`) are opened in-process. + +## Surfaces + +### CLI + +```powershell +.\.venv\Scripts\agentmemory.exe --help +``` + +Running `agentmemory` with no arguments opens an interactive shell with first-run onboarding and slash commands (`/help`, `/install`, `/configure`, `/provider`, `/doctor`, `/start`, `/stop`, `/ui`, `/mcp`, `/status`, `/clients`, `/snippets`, `/exit`). Subcommands are automation-friendly. The groups: + +| Group | Commands | +|---|---| +| Setup | `install`, `configure`, `profile-list`, `profile-create`, `profile-use` | +| Runtime | `start-api`, `stop-api`, `doctor`, `mcp-smoke`, `snippets` | +| Clients | `connect-clients`, `disconnect-clients`, `status-clients`, `doctor-clients` | +| Data | `list-scopes`, `export-memories`, `import-memories`, `reconcile-memories`, `rebuild-scope-registry` | +| Providers | `provider-certify` | + +Day-to-day memory operations (add, search, list, get, update, delete, health, pages) are in the data CLI: `python -m agentmemory.ops_cli `; for example `add --message "..." --user-id u1` and `search "query" --user-id u1 --no-rerank`. `add` stores verbatim unless you pass `--infer`. + +### HTTP API + +Served by the local API process (default `127.0.0.1:8765`; `start-api` picks a free port if the configured one is busy). Routes in [api.py](agentmemory/api.py): + +| Route | Purpose | +|---|---| +| `GET /health` | Liveness (open); full diagnostics for authorized callers | +| `GET /metrics` | Prometheus text metrics (authorized) | +| `POST /add`, `/search`, `/search/page`, `/update` | Memory operations | +| `GET /memories`, `/memories/page`, `/memories/`; `DELETE /memories/` | Read and delete | +| `GET/PATCH/DELETE /admin/memories...`, `POST /admin/memories//pin`, `GET /admin/stats`, `/admin/stats/operations`, `/admin/scopes`, `/admin/scopes/page`, `/admin/clients` | Operator surface used by the browser UI | +| `POST /mcp` | MCP over HTTP (JSON-RPC, single or batch) | +| `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/oauth/authorize`, `/oauth/token`, `/register` | OAuth 2.1 and Dynamic Client Registration | + +Without a configured token and without OAuth, the API is open (intended for local-only use). With `AGENTMEMORY_API_TOKEN` or OAuth enabled, everything except `/health`, the discovery documents and the OAuth authorize/token/register endpoints requires a bearer credential. Error responses use typed `error_type` values mapped to HTTP statuses. + +### MCP + +`agentmemory-mcp` (via `scripts/run-agentmemory-mcp.ps1` or `.sh`) runs a stdio MCP server that supports protocol versions `2025-06-18` and `2024-11-05`, lists the 14 tools, and validates each call's arguments against the tool's input schema. `agentmemory mcp-smoke` runs an initialize / tools-list / tools-call self-test. The same tool set is served over HTTP at `POST /mcp` for remote clients. + +### Main Commands ```powershell .\.venv\Scripts\agentmemory.exe --help @@ -251,7 +393,7 @@ This is one of the clearest examples of why a memory runtime layer can be useful `agentmemory snippets` prints ready-to-use Claude Code and Gemini CLI snippets. -## Root Entry Points +### Root Entry Points For users who want one obvious launcher from the repository root, AgentMemory also ships thin root wrappers for both Windows and POSIX shells. @@ -275,6 +417,55 @@ macOS / Linux: These wrappers delegate to the maintained scripts in `scripts/`, so the root stays user-friendly without moving the operational implementation out of `scripts/`. +## Providers + +| Provider | Status | Semantic search | Text search | Update | Delete | Pagination | Scope needed for list/search | Transport | +|---|---|---|---|---|---|---|---|---| +| `mem0` | certified (policy: certified with skips) | yes (rerank supported) | no | yes | yes | single-page fallback | yes | owner-process proxy | +| `localjson` | certified | no | yes | yes | yes | yes | no | direct | +| `claude_memory` | experimental | no | yes | no | no | no | no | direct | +| `mempalace` | experimental | yes | no | no | yes | no | no | direct | + +The table reflects each provider's declared `capabilities()` and registry metadata in the code. Certification means a provider passes the shared contract harness; it is not a claim about retrieval quality. + +### Mem0 + +Use `mem0` when you want: + +- semantic retrieval +- OpenRouter-backed extraction and embeddings +- the main production path of this repo + +Notes: + +- requires `OPENROUTER_API_KEY` +- uses owner-process proxy transport in this repo +- is the current default provider (the quick start above deliberately starts with `localjson` instead) +- keeps its data in an embedded store under the runtime data directory; the default model settings use OpenRouter-hosted models (configurable with `configure` flags such as `--embedding-model`) +- the package pins `mem0ai==1.0.10` + +### Local JSON + +Use `localjson` when you want: + +- zero external API dependency +- a simple built-in backend for tests and demos +- an inspectable on-disk provider (a single JSON file, `data/localjson-memories.json` by default, overridable with `--storage-path`) + +### Claude Memory (experimental) + +`claude_memory` is a conservative file-backed adapter over Claude Code memory surfaces: it can read user-level memory, project memory and auto-memory (each switchable with `--no-user-memory` / `--no-auto-memory`), and writes only into an AgentMemory-owned directory (by default `.claude/rules/agentmemory` under the project's Git root). It declares no update, no delete and no scope inventory. + +### MemPalace (experimental) + +`mempalace` is a local semantic provider backed by an AgentMemory-owned MemPalace collection (`--palace-path`, `--palace-id`, `--collection-name`). Its install requirement (`mempalace==3.3.5`) is installed with the provider; it declares no update and no filters. + +Details and adapter rules: [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md), [Future Memory Providers](docs/future-memory-providers/README.md). + +## Client wiring + +`agentmemory connect-clients` detects supported clients and adds AgentMemory as an MCP server: Codex, Claude Code, Claude Desktop, Gemini CLI, Qwen CLI, Cursor, VS Code / Copilot, Roo Code, KiloCode and Cline. Where a client's configuration is a file, the previous file is backed up under `data/backups/client-configs`. `disconnect-clients` removes it again; `status-clients` and `doctor-clients` report detection, configuration state and local MCP health in `--json`, `--table` or `--compact` form (stable exit codes for scripting). The workflow is Windows-first; the runtime itself also runs on Linux and macOS, but client auto-connect on those platforms is less exercised. For clients not on the list, use `agentmemory snippets` or point any MCP client at `scripts/run-agentmemory-mcp.ps1` / `.sh`. + ## Remote MCP Connectors (Claude.ai, ChatGPT) When AgentMemory is exposed on a public URL, it speaks MCP over HTTP at `POST /mcp` and supports OAuth 2.1 with Dynamic Client Registration (RFC 7591). Hosted MCP clients like Claude.ai Custom Connectors or ChatGPT Custom Connectors discover the server and register themselves without any operator-issued client_id. @@ -295,6 +486,37 @@ Server-side knobs: - `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` — per-IP cap on /register (default 20). - `AGENTMEMORY_PUBLIC_URL` — the canonical https URL the server should advertise in OAuth discovery. +Access tokens last 7 days and refresh tokens 30 days; a refresh rotates the pair and invalidates the old refresh token. Registered clients are stored with hashed secrets. Read [Security and identity](#security-and-identity) before exposing the server: the authorize step auto-approves and there is no end-user login. + +## Security and identity + +- **Local by default.** The API binds `127.0.0.1`; with no token and no OAuth it accepts anonymous local calls. Set `AGENTMEMORY_API_TOKEN` (the root `docker-compose.yml` refuses to start without one) before binding to anything other than loopback. +- **Guards.** A per-credential token-bucket rate limit (default 60 per minute, `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`), a per-IP cap on `/register`, a request body cap (default 16 MiB, `AGENTMEMORY_MAX_BODY_BYTES`), and `AGENTMEMORY_DISABLE_UI=1` to turn the browser UI off on remote deployments. +- **No end-user authentication.** AgentMemory has no login. By default `user_id` is taken from the request payload, so any valid credential can name any scope. +- **Opt-in identity binding.** With `AGENTMEMORY_ENFORCE_AUTH_USER_ID=1` and a credential that carries a bound identity (configured per OAuth client, for example `AGENTMEMORY_OAUTH_BOUND_USER_ID`), a matching `user_id` passes, a missing one is filled in, and a different one is refused with `ProviderIdentityError` (HTTP 403). Operations that range over the whole store and the `/admin/*` routes are refused to a bound credential. The check lives in the single wrapper every operation passes through, so HTTP, MCP and CLI share it. +- **What binding does not give you.** It is not tenant isolation: it is only as trustworthy as whatever issued the token; it is void while dynamic registration is enabled and unbound credentials exist; it must be set on the process clients talk to; `agent_id` and `run_id` are not bound; providers do not partition storage. Read [Auth identity binding](docs/AUTH_IDENTITY_BINDING.md) and [SECURITY.md](SECURITY.md) first. + +## Memory semantics + +AgentMemory executes declared semantics consistently; it does not guess intent ([Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md)). + +- **`infer` is off by default.** `memory_add` stores the text verbatim. With `infer=true` the provider's LLM may extract, rewrite or split the input (one LLM call per write); the response then says so (`transformed`, `original_text`, `stored_text`) and extra records appear under `additional_records`. The CLI mirrors this: `--infer` is explicit opt-in. +- **Dedup on add (opt-in).** `dedup=true` runs a semantic search in the same scope first and returns the matching existing record (`dedup_hit`) instead of inserting a duplicate. Needs a scope and a provider with semantic search; the similarity threshold is not user-tunable yet. +- **TTL is opt-in and off by default.** `metadata.ttl_seconds` or `metadata.expires_at` are rejected unless the operator sets `AGENTMEMORY_ALLOW_TTL=1`. When enabled, expired records are hidden from reads and a background sweeper (default every 10 minutes, `AGENTMEMORY_TTL_SWEEP_MINUTES`) hard-deletes them; a mistyped unit can destroy a record permanently, which is why it is off. TTL is caller-controlled metadata, not automatic short-term/long-term classification. +- **Stale warnings.** If a record's `metadata.stale_after` has passed, search results carry a `stale_warning` (the record is not hidden) so callers re-verify time-bound facts. +- **Reconcile.** `reconcile-memories` / `memory_reconcile` is a read-only hygiene check that lists likely conflicting memory pairs in a scope. It does not modify storage and is an early heuristic, not a guarantee. + +## Export, import and hygiene + +- `agentmemory export-memories ` and `import-memories ` (also MCP `memory_export` / `memory_import`) move memories as provider-neutral JSONL by walking the scope inventory. Import replays records through `add` with `infer=false` for round-trip fidelity. The path is resolved on the machine running the operation, so over a remote MCP connection it is a server-side path. Export and import are refused to identity-bound credentials. +- `rebuild-scope-registry` re-seeds the scope inventory for the active provider. +- Writes of runtime files (state, registries, tokens) go through atomic write helpers. + +## Profiles and doctor + +- **Profiles.** `profile-list`, `profile-create [--copy-from ...]` and `profile-use ` manage named runtime profiles (for example `default`, `staging`); `AGENTMEMORY_PROFILE` selects one for a process and `AGENTMEMORY_HOME` points at the runtime root. +- **`doctor`.** Checks the venv, configuration, key availability and health, and reports the active profile, runtime id, config version, API runtime state and provider contract version, with provider-specific guidance. A missing `.env` is informational so the `localjson` path stays quiet. `start-api` distinguishes a stale PID from a foreign process on the port. + ## Browser UI The local API also serves a browser UI at: @@ -313,52 +535,58 @@ Current browser UI capabilities: - delete low-value memories - client status summary -## Providers +The UI is a Vue 3 single-page app in [`web/`](web/): a table and a timeline view, an inspector, bulk selection, an add-memory dialog, scope filters, a `/me` view for one user's memories, a command palette (`Ctrl/Cmd+K` or `/`), keyboard shortcuts (press `?` in the UI) and a status strip with live operation counters. -### Mem0 +**Build step.** The compiled bundle is not committed. When you run from a source checkout, build it once, otherwise `/` answers with a 503 explaining that the UI bundle is not built: -Use `mem0` when you want: +```sh +cd web && npm install && npm run build +``` -- semantic retrieval -- OpenRouter-backed extraction and embeddings -- the main production path of this repo +The Docker image builds it for you. Set `AGENTMEMORY_DISABLE_UI=1` to switch the UI off. -Notes: +## Operations and deployment -- requires `OPENROUTER_API_KEY` -- uses owner-process proxy transport in this repo -- is the current default provider +### Metrics -### Local JSON +The API collects in-process counters, latency histograms and an estimate of OpenRouter token usage and cost, rendered as Prometheus text at `GET /metrics` (authorized) and as JSON at `/admin/stats/operations`. They live in memory; a restart clears the history. -Use `localjson` when you want: +### Docker and deployment -- zero external API dependency -- a simple built-in backend for tests and demos -- an inspectable on-disk provider +- The [Dockerfile](Dockerfile) builds the web console in a first stage and runs the API (`python -m agentmemory.api`) in a second. +- The root [docker-compose.yml](docker-compose.yml) requires `AGENTMEMORY_API_TOKEN` and publishes the port on `127.0.0.1` by default (`AGENTMEMORY_BIND_ADDR`, `AGENTMEMORY_PUBLISHED_PORT`). +- [deploy/](deploy/) and [docs/DEPLOY.md](docs/DEPLOY.md) describe a reverse-proxy (Traefik) deployment as remote MCP plus HTTP, with a redeploy script that works around a Compose v2 external-network drift (see [Current Limitations](#current-limitations)) and a backup script. -## Documentation Map +## Reference -- [Start Here](docs/START_HERE.md) -- [Why AgentMemory Exists](docs/WHY_AGENTMEMORY.md) -- [Mem0 vs AgentMemory](docs/MEM0_VS_AGENTMEMORY.md) -- [What AgentMemory Adds To Mem0](docs/MEM0_WITH_AGENTMEMORY_VALUE.md) -- [What AgentMemory Actually Adds](docs/WHAT_AGENTMEMORY_ACTUALLY_ADDS.md) -- [Use Cases](docs/USE_CASES.md) -- [Architecture](docs/ARCHITECTURE.md) -- [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md) -- [Backlog / Current Limitations](docs/planning/BACKLOG.md) -- [Positioning Assets](docs/POSITIONING.md) -- [Roadmap](docs/planning/ROADMAP.md) -- [Contributing](CONTRIBUTING.md) -- [Security](SECURITY.md) -- [Support](SUPPORT.md) +### Environment variables -## Examples +| Variable | Purpose | +|---|---| +| `OPENROUTER_API_KEY` | Key for the `mem0` provider | +| `AGENTMEMORY_API_HOST`, `AGENTMEMORY_API_PORT` | API bind address and port (default `127.0.0.1:8765`) | +| `AGENTMEMORY_API_TOKEN` | Pre-shared bearer for HTTP and `/mcp` | +| `AGENTMEMORY_PUBLIC_URL` | Public base URL advertised in OAuth discovery | +| `AGENTMEMORY_OAUTH_CLIENT_ID`, `AGENTMEMORY_OAUTH_CLIENT_SECRET`, `AGENTMEMORY_OAUTH_BOUND_USER_ID` | Static OAuth client and its bound identity | +| `AGENTMEMORY_OAUTH_DISABLE_DCR`, `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` | Dynamic registration switch and limit | +| `AGENTMEMORY_OAUTH_STORE`, `AGENTMEMORY_OAUTH_TOKEN_STORE` | Override OAuth store paths | +| `AGENTMEMORY_ENFORCE_AUTH_USER_ID` | Opt-in identity binding | +| `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`, `AGENTMEMORY_MAX_BODY_BYTES` | Rate limit and body cap | +| `AGENTMEMORY_DISABLE_UI` | Disable the browser UI | +| `AGENTMEMORY_ALLOW_TTL`, `AGENTMEMORY_TTL_SWEEP_MINUTES` | Enable TTL and tune the sweeper | +| `AGENTMEMORY_PROFILE`, `AGENTMEMORY_HOME` | Select a profile and the runtime root | +| `AGENTMEMORY_BIND_ADDR`, `AGENTMEMORY_PUBLISHED_PORT` | Docker Compose publish address and port | +| `AGENTMEMORY_*_MCP_CONFIG`, `AGENTMEMORY_CLAUDE_DESKTOP_CONFIG` | Override client config file locations (for example VS Code, Roo, Kilo, Cline, Claude Desktop) | -- [HTTP Python Roundtrip](examples/http_python_roundtrip.py) -- [Shared Runtime Demo](examples/shared-runtime-demo.md) -- [MCP Demo](examples/mcp-demo.md) +`AGENTMEMORY_OWNER_PROCESS` is set by the runtime itself for the owner process; you do not set it by hand. + +### Files on disk + +Under the runtime root: `.env`, `agentmemory.config.json`, `data/` (provider data, the scope registry, API PID/state files, `oauth_clients.json`, `oauth_tokens.json`, client-config backups). All are local-only. + +### Repository layout + +`agentmemory/` (package: `providers/`, `runtime/`, `certification/`, CLI, API, MCP, OAuth, clients), `web/` (Vue console), `scripts/` and root launchers, `deploy/`, `docs/`, `examples/`, `snippets/`, `tests/`. ## Validation @@ -371,9 +599,11 @@ Useful local checks: .\.venv\Scripts\python.exe -m agentmemory.ops_cli list-scopes --limit 20 ``` +Continuous integration runs the unit tests on Ubuntu and Windows (Python 3.13) and a separate provider certification policy check. + ## Provider Certification -AgentMemory treats providers as adapter layers behind one shared contract. +AgentMemory treats providers as adapter layers behind one shared contract. A provider is certified only when it returns normalized payloads, enforces its declared capabilities, raises typed errors, and passes the reusable contract harness; otherwise it is experimental. Registry statuses are `certified`, `provisional`, `experimental` and `test-only` (a fake in-memory provider proves the harness is backend-agnostic). Useful references: @@ -389,6 +619,77 @@ Quick helper commands: .\.venv\Scripts\provider-certify.exe localjson --json --run-tests --summary-only ``` +`provider-certify-ci --json` checks that each provider still meets its expected policy status (`localjson`: certified; `mem0`: certified with skips). + +## Troubleshooting + +- **`agentmemory` not found.** Use the explicit `.venv` paths shown in the quick start. +- **API will not start or the port is busy.** Run `doctor` and read the blocking errors; `start-api` selects a free port and updates the runtime config, and distinguishes a stale PID from a foreign listener. +- **`mem0` fails.** Go back to `localjson`; confirm `OPENROUTER_API_KEY` is set. Some hosts cannot reach the embedding backends; `docs/DEPLOY.md` describes the symptom and a proxy-sidecar workaround. +- **Browser UI returns 503.** Build the bundle: `cd web && npm install && npm run build`. +- **Remote client gets 401.** Send `Authorization: Bearer ` or complete the OAuth flow; `/health` stays open. +- **`add` with TTL is rejected.** TTL is off by default; see [Memory semantics](#memory-semantics). +- **A scope looks empty or counts are off.** Run `agentmemory rebuild-scope-registry`. + +## Current Status + +- `public alpha` +- local-first product +- runtime core works on Windows, Linux, and expected macOS paths +- Windows-first client integration workflow +- `mem0` is the main semantic provider +- `localjson` is the built-in testing and demo provider +- `claude_memory` is the conservative file-backed adapter for Claude Code memory surfaces +- `mempalace` is the experimental local semantic provider backed by an AgentMemory-owned MemPalace collection +- provider contract, operation registry, transport adapters, and runtime policy are implemented +- diagnostics and scope discovery are part of the current product surface + +## Current Limitations + +AgentMemory is usable as a local shared-memory runtime, but it is still a public alpha. The current risk/bug index lives in [Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md). + +Important current limitations: + +- TTL exists as optional expiry support. It is caller-controlled metadata, not automatic short-term/long-term classification. Providers with degraded scope registry sync may require `rebuild-scope-registry` before TTL sweeps can be considered complete. +- `mem0` uses the safe single-page fallback for pagination until a backend-safe cursor strategy is implemented. +- Compose v2 external-network drift is mitigated by `deploy/redeploy.sh`, but the upstream root cause remains outside this repo. + +Also worth knowing (from the backlog and security docs): + +- `infer` is off by default; with `infer=true` content can be rewritten by the provider's LLM. +- Dynamic registration and the auto-approving authorize step mean a reachable server can mint unbound tokens; identity binding is only meaningful with DCR disabled and every client bound. It is not tenant isolation. +- The sweeper hard-deletes expired records (no recovery window yet); a soft-delete window is a backlog item. +- Metrics are in memory and reset on restart. +- Client auto-connect is Windows-first. +- Open P1 backlog items include an identity for DCR-created OAuth clients and a dead-man backup ping. + +## Documentation Map + +- [Start Here](docs/START_HERE.md) +- [Why AgentMemory Exists](docs/WHY_AGENTMEMORY.md) +- [Mem0 vs AgentMemory](docs/MEM0_VS_AGENTMEMORY.md) +- [What AgentMemory Adds To Mem0](docs/MEM0_WITH_AGENTMEMORY_VALUE.md) +- [What AgentMemory Actually Adds](docs/WHAT_AGENTMEMORY_ACTUALLY_ADDS.md) +- [Use Cases](docs/USE_CASES.md) +- [Architecture](docs/ARCHITECTURE.md) +- [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md) +- [Auth identity binding](docs/AUTH_IDENTITY_BINDING.md) +- [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md) and [Provider Certification](docs/PROVIDER_CERTIFICATION.md) +- [Deploy](docs/DEPLOY.md) +- [Backlog / Current Limitations](docs/planning/BACKLOG.md) +- [Positioning Assets](docs/POSITIONING.md) +- [Roadmap](docs/planning/ROADMAP.md) +- [Changelog](CHANGELOG.md) +- [Contributing](CONTRIBUTING.md) +- [Security](SECURITY.md) +- [Support](SUPPORT.md) + +## Examples + +- [HTTP Python Roundtrip](examples/http_python_roundtrip.py) +- [Shared Runtime Demo](examples/shared-runtime-demo.md) +- [MCP Demo](examples/mcp-demo.md) + ## License [MIT](LICENSE). diff --git a/README.ru.md b/README.ru.md index 7fefd34..2e0269c 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,6 +1,6 @@

AgentMemory: несколько роботов-ИИ-инструментов и скрипт читают и записывают заметки через одну общую среду памяти, за которой стоит сменное хранилище

AgentMemory

-

Одна общая локальная память для ваших ИИ-инструментов и скриптов — CLI, HTTP API и MCP поверх сменного бэкенда памяти, например mem0.

+

Одна общая локальная память для ваших ИИ-инструментов и скриптов: единый набор операций памяти через CLI, HTTP API и MCP (локально или удалённо), сменные провайдеры хранения вроде mem0, встроенная диагностика, подключение клиентов, веб-консоль и набор для сертификации провайдеров.

License: MIT Python 3.11+ @@ -16,7 +16,106 @@ agentmemory configure --provider localjson # API-ключи не нужны agentmemory start-api # один локальный рантайм, несколько клиентских интерфейсов ``` -AgentMemory — это общий локальный рантайм памяти для ИИ-клиентов и агентов. Он стоит над бэкендом памяти вроде `mem0` и даёт одну стабильную поверхность через CLI, HTTP API и MCP: то, что сохранил один инструмент, может вспомнить другой. Сейчас это **публичная альфа**; прежде чем на него опираться, прочитайте [Текущий статус](#текущий-статус) и [Текущие ограничения](#текущие-ограничения). +AgentMemory — это общий локальный рантайм памяти для ИИ-клиентов и агентов. Он стоит над бэкендом памяти (*провайдером*: `mem0`, встроенное JSON-хранилище и два экспериментальных адаптера) и даёт **один стабильный набор из 14 операций памяти** через CLI, локальный HTTP API и MCP-сервер: то, что сохранил один инструмент, может вспомнить другой. Вокруг этого ядра он добавляет: транспорт через процесс-владелец для бэкендов, которые нельзя открывать из многих процессов сразу; подключение к десяти ИИ-клиентам и редакторам одной командой; удалённую MCP-точку с поддержкой bearer-токена и OAuth 2.1 (Dynamic Client Registration); экспорт и импорт в JSONL; опциональную семантику памяти (дедупликация, TTL, предупреждения об устаревании, проверка конфликтов только на чтение); `doctor`, объясняющий, что не так; браузерную консоль; метрики; файлы для развёртывания в Docker; и набор для сертификации провайдеров, чтобы добавлять новые бэкенды. + +Это **публичная альфа** (версия 0.1.0, local-first, не рассчитана на враждебные мультиарендные сценарии и открытую сеть). Прежде чем на неё опираться, прочитайте [Текущий статус](#текущий-статус) и [Текущие ограничения](#текущие-ограничения). + +**Содержание:** [В двух словах](#в-двух-словах) · [Что внутри](#что-внутри) · [Как это работает](#как-это-работает) · [Быстрый старт](#quickstart) · [Концепции](#концепции) · [Интерфейсы](#интерфейсы) · [Провайдеры](#провайдеры) · [Подключение клиентов](#подключение-клиентов) · [Удалённый MCP](#удалённые-mcp-коннекторы-claudeai-chatgpt) · [Безопасность](#безопасность-и-идентичность) · [Семантика памяти](#семантика-памяти) · [Переносимость данных](#экспорт-импорт-и-гигиена) · [Веб-консоль](#браузерный-интерфейс) · [Эксплуатация](#эксплуатация-и-развёртывание) · [Справочник](#справочник) · [Устранение неполадок](#устранение-неполадок) · [Статус](#текущий-статус) · [Ограничения](#текущие-ограничения) · [Карта документации](#карта-документации) + +## В двух словах + +### Проблема + +У каждого ИИ-инструмента свои заметки, а то и никаких. Агент для программирования узнаёт ваши предпочтения, а следующий инструмент, скрипт или другой агент начинает с нуля. Бэкенды памяти вроде `mem0` решают задачу *хранения и ранжирования* воспоминаний, но у каждого свой SDK, свои формы записей и свои особенности: одни используют локальные файлы, которые может открыть только один процесс, другим нужны API-ключи, третьи вообще недоступны из хостируемого ИИ-клиента. Без общего слоя каждый инструмент заново пишет интеграцию и ведёт себя по-своему. + +### Для кого это + +Для тех, кто запускает несколько ИИ-клиентов или агентов (Claude Code, Codex, Gemini CLI, Cursor и подобные) и скрипты и хочет, чтобы они делили одну память на своей машине; для тех, кто хочет открыть эту память хостируемым клиентам вроде пользовательских коннекторов Claude.ai или ChatGPT; и для разработчиков, которые хотят подключить за тем же контрактом ещё один бэкенд памяти. + +### Что вы получаете + +- **Одна память для многих клиентов.** Одни и те же операции (add, search, list, get, update, delete, области, экспорт/импорт, reconcile, health) доступны из CLI, HTTP API и MCP-инструментов, с одной и той же валидацией и одними и теми же типизированными ошибками. +- **Сменный бэкенд.** Провайдеры стоят за единым контрактом с нормализованными записями и заявленными возможностями. Начните со встроенного `localjson` без зависимостей; для семантического поиска переключитесь на `mem0`. +- **Рантайм, который справляется с капризными бэкендами.** Если бэкенд должен открываться одним процессом, его запускает один процесс-*владелец*, а всё остальное ходит через него. +- **Помощь с настройкой.** `connect-clients` подключает AgentMemory к найденным клиентам (сначала Windows), `doctor` и `doctor-clients` говорят, что не так, именованные профили разделяют окружения. +- **Удалённый доступ, когда он нужен.** MCP поверх HTTP на `/mcp`, bearer-токен или OAuth 2.1 с Dynamic Client Registration, ограничения частоты и размера запроса. +- **Способы посмотреть и перенести данные.** Браузерная консоль для просмотра и правки воспоминаний, экспорт/импорт в JSONL, метрики в формате Prometheus, файлы для Docker. + +### Чем это не является + +- Это не движок *политики* памяти. Он не решает, что стоит запомнить и как долго это должно жить; это решает вызывающая сторона. TTL существует только как опциональные метаданные от вызывающей стороны ([Runtime boundaries](docs/RUNTIME_BOUNDARIES.md)). +- Это не сам движок памяти. Качество хранения и поиска определяет выбранный провайдер. +- Это не система аутентификации людей. Входа пользователя нет; шаг авторизации OAuth опознаёт *клиента*, а не человека. Необязательная привязка идентичности — **не изоляция арендаторов** ([подробности](#безопасность-и-идентичность)). +- Не рассчитан на враждебные мультиарендные сценарии и открытую сеть ([SECURITY.md](SECURITY.md)). +- Не нужен, если память принадлежит одному Python-приложению и вам не нужен доступ по MCP или HTTP: прямая интеграция с `mem0` обычно проще. + +### Глоссарий + +| Термин | Что означает здесь | +|---|---| +| **Провайдер** | Адаптер бэкенда памяти (`mem0`, `localjson`, `claude_memory`, `mempalace`) за общим контрактом. | +| **Контракт провайдера** | Стабильная граница: нормализованные `MemoryRecord` / `DeleteResult`, формы страниц, заявленные возможности, политика рантайма и типизированные ошибки. | +| **Операция** | Одно из 14 общих действий (например, `add`, `search`), описанное один раз в реестре операций и доступное во всех интерфейсах. | +| **Интерфейс (surface)** | Способ добраться до операций: CLI, HTTP API, MCP-сервер, интерактивная оболочка, браузерный интерфейс. | +| **Область (scope)** | `user_id` / `agent_id` / `run_id`, которым принадлежит воспоминание. Некоторым провайдерам (`mem0`) область нужна для list и search. | +| **Процесс-владелец** | Единственный локальный процесс API, который владеет бэкендом, не допускающим параллельного открытия; остальные клиенты ходят через него. | +| **MCP** | Model Context Protocol — способ, которым ИИ-клиенты вызывают инструменты вроде `memory_search`. | +| **DCR** | Dynamic Client Registration в OAuth (RFC 7591): хостируемый клиент регистрируется сам, client id вручную выдавать не нужно. | +| **Сертификация** | Проверка того, что провайдер соблюдает контракт (общий набор тестов плюс `provider-certify`). | + +## Что внутри + +Метки статуса: без метки — реализовано в этом репозитории; **экспериментально** — реализовано, но не сертифицировано; **opt-in** — реализовано, но выключено, пока вы не включите; **планируется** — только дизайн или дорожная карта. + +### Один рантайм, три основных интерфейса + +- **Реестр операций.** Четырнадцать операций описаны один раз и вызываются из CLI, HTTP и MCP через одну и ту же валидацию, формирование типизированных ошибок и проверку идентичности. → [Концепции](#концепции) +- **CLI.** `agentmemory` — установка, настройка, диагностика, управление API, подключение клиентов, профили, экспорт/импорт и сертификация; `agentmemory.ops_cli` — операции с данными. Без аргументов открывает интерактивную оболочку с первичной настройкой и slash-командами. → [Интерфейсы](#интерфейсы) +- **HTTP API.** Локальный сервер на стандартной библиотеке с маршрутами памяти, административными маршрутами, `/health`, `/metrics` и `/mcp`. → [HTTP API](#http-api) +- **MCP-сервер.** Stdio-сервер с 14 инструментами `memory_*` и те же инструменты поверх HTTP на `POST /mcp`; аргументы каждого вызова проверяются по входной схеме инструмента. → [MCP](#mcp) + +### Провайдеры + +- **`mem0`.** Основной семантический провайдер: семантический поиск с rerank, фильтры, update/delete, встроенное хранилище, транспорт через процесс-владелец. Нужен ключ OpenRouter. → [Провайдеры](#провайдеры) +- **`localjson`.** Встроенный, без API-ключей: текстовый поиск, пагинация, JSON-файл, который можно просмотреть. Для тестов и демо. → [Провайдеры](#провайдеры) +- **`claude_memory`** (**экспериментально**). Консервативный файловый адаптер для поверхностей памяти Claude Code; без update и delete. → [Провайдеры](#провайдеры) +- **`mempalace`** (**экспериментально**). Локальный семантический провайдер на базе коллекции MemPalace, принадлежащей AgentMemory; без update. → [Провайдеры](#провайдеры) + +### Подключение клиентов + +- **`connect-clients`.** Находит и настраивает Codex, Claude Code, Claude Desktop, Gemini CLI, Qwen CLI, Cursor, VS Code / Copilot, Roo Code, KiloCode и Cline; `disconnect-clients`, `status-clients` и `doctor-clients` (вывод json / table / compact) замыкают цикл. Сначала Windows. → [Подключение клиентов](#подключение-клиентов) +- **Сниппеты и лаунчеры.** `agentmemory snippets` печатает конфигурацию для Claude Code и Gemini CLI; PowerShell- и POSIX-лаунчеры лежат в корне репозитория. → [Точки входа в корне репозитория](#точки-входа-в-корне-репозитория) + +### Удалённый доступ и безопасность + +- **Удалённый MCP.** `POST /mcp` с заранее выданным bearer-токеном и/или OAuth 2.1 (код авторизации, ротация refresh-токенов, документы discovery, Dynamic Client Registration). → [Удалённый MCP](#удалённые-mcp-коннекторы-claudeai-chatgpt) +- **Защитные меры.** Лимит частоты на каждый учётный токен, лимит на IP для регистрации, ограничение размера тела запроса, браузерный интерфейс можно отключить. → [Безопасность](#безопасность-и-идентичность) +- **Привязка идентичности** (**opt-in**). Привяжите учётные данные к одному `user_id`, чтобы они не могли указать чужую область. Это не изоляция арендаторов. → [Безопасность](#безопасность-и-идентичность) + +### Семантика памяти (всё управляется вызывающей стороной) + +- **`infer`** (по умолчанию выключен). Воспоминания хранятся дословно, пока вызывающая сторона не попросит LLM провайдера извлечь или переписать их; переписывание видно в ответе. → [Семантика памяти](#семантика-памяти) +- **Дедупликация при добавлении** (**opt-in**), **истечение по TTL** (**opt-in**, по умолчанию выключено), **предупреждения stale-after** в результатах поиска и **проверка конфликтов** только на чтение (`reconcile`). → [Семантика памяти](#семантика-памяти) +- **Инвентаризация областей.** `list-scopes` читает реестр, принадлежащий AgentMemory; `rebuild-scope-registry` его восстанавливает. → [Концепции](#концепции) + +### Данные, диагностика и эксплуатация + +- **Экспорт / импорт.** JSONL, не привязанный к провайдеру. → [Экспорт, импорт и гигиена](#экспорт-импорт-и-гигиена) +- **`doctor`, профили и подсказки.** Проверяет venv, конфигурацию, ключи и состояние; именованные профили вроде `default` и `staging`; подсказки по провайдеру. → [Профили и doctor](#профили-и-doctor) +- **Метрики.** Счётчики и задержки в процессе, с текстовой точкой Prometheus. → [Метрики](#метрики) +- **Docker и файлы развёртывания.** Dockerfile, который заодно собирает веб-консоль, compose-файлы и руководство по развёртыванию за Traefik. → [Эксплуатация и развёртывание](#эксплуатация-и-развёртывание) + +### Веб-консоль + +- **Браузерный интерфейс.** Обозреватель воспоминаний (таблица и лента), инспектор деталей, правка, закрепление, удаление, добавление, массовый выбор, фильтры по областям, палитра команд и горячие клавиши, строка статуса рантайма. При запуске из исходников нужна разовая сборка фронтенда. → [Браузерный интерфейс](#браузерный-интерфейс) + +### Создание и сертификация провайдеров + +- **Правила адаптеров и набор контрактных тестов.** Переиспользуемый набор тестов, от которого наследуется каждый провайдер; `provider-certify` и `provider-certify-ci` показывают и проверяют статус сертификации. → [Сертификация провайдеров](#сертификация-провайдеров) + +### Ещё не сделано + +Только планируется или предлагается, в коде этого нет: документо-ориентированный провайдер на основе git и Markdown, другие провайдеры (например, Zep, Hindsight, Cognee, Graphiti), этапы ревью и совместной работы в консоли, окно мягкого удаления для TTL-уборщика, защита от абсурдных значений TTL, фильтр `memory_type`, курсорная пагинация для `mem0` и схема идентичности для клиентов OAuth, созданных через DCR. См. [ROADMAP](docs/planning/ROADMAP.md), [BACKLOG](docs/planning/BACKLOG.md) и [Future Memory Providers](docs/future-memory-providers/README.md). ## Зачем нужен AgentMemory? @@ -41,17 +140,6 @@ AgentMemory — это общий локальный рантайм памяти Более конкретные сценарии: [Use Cases](docs/USE_CASES.md), [Shared Runtime Demo](examples/shared-runtime-demo.md), [MCP Demo](examples/mcp-demo.md). -## Возможности - -- **Один рантайм, три интерфейса** — CLI, локальный HTTP API и MCP работают через одни и те же общие операции. -- **Сменные провайдеры** — `mem0` (основной семантический путь), `localjson` (встроенный провайдер для тестов и демо), `claude_memory` (консервативный файловый адаптер для поверхностей памяти Claude Code) и `mempalace` (экспериментальный локальный семантический провайдер). -- **Подключение клиентов** — `connect-clients` автоматически подключает AgentMemory к найденным ИИ-клиентам и редакторам; `status-clients` и `doctor-clients` проверяют результат. Сначала Windows. -- **Браузерный интерфейс** — обзор рантайма, обозреватель воспоминаний, редактирование, закрепление и удаление, статус клиентов. -- **Удалённые MCP-коннекторы** — MCP поверх HTTP на `POST /mcp` с OAuth 2.1 и Dynamic Client Registration — для хостируемых клиентов вроде пользовательских коннекторов Claude.ai и ChatGPT. -- **Встроенная диагностика** — `doctor` проверяет venv, конфигурацию, наличие ключей и состояние; осведомлённые о возможностях подсказки — часть продукта. -- **Опциональная семантика жизненного цикла** — TTL-истечение, если вызывающая сторона решит им пользоваться. -- **Сертификация провайдеров** — провайдеры проверяются по единому общему контракту (`provider-certify`). - ## Как это работает

@@ -147,6 +235,12 @@ python3 -m venv .venv - `start-api` чисто стартует с настроенным провайдером - можно снова запустить `.\.venv\Scripts\python.exe .\examples\http_python_roundtrip.py` +### Дальнейшие шаги + +- Подключите ИИ-клиенты: `agentmemory connect-clients`, затем `agentmemory status-clients --compact` ([Подключение клиентов](#подключение-клиентов)). +- Посмотрите, что сохранилось, в браузерной консоли ([Браузерный интерфейс](#браузерный-интерфейс); из исходников нужна разовая сборка `npm install && npm run build` в `web/`). +- Запустите самопроверку MCP: `agentmemory mcp-smoke`. + ### Демо общего рантайма Канонический сценарий знакомства: @@ -176,6 +270,8 @@ AgentMemory создаёт локальное состояние рантайм - Если порт API занят, `start-api` должен выбрать свободный; повторяйте скрипт roundtrip только после того, как напечатан URL API. - Если путь с `mem0` не работает, вернитесь к `localjson`. Первый путь проверки не должен зависеть от внешних API-ключей и настройки семантического провайдера. +Больше — в разделе [Устранение неполадок](#устранение-неполадок). + ## Снимок архитектуры ```mermaid @@ -199,30 +295,34 @@ flowchart TD - [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md) - [Future Memory Providers](docs/future-memory-providers/README.md) -## Текущий статус +## Концепции -- `public alpha` (публичная альфа) -- локальный продукт (local-first) -- ядро рантайма работает на Windows, Linux и ожидаемо на macOS -- процесс интеграции с клиентами сначала ориентирован на Windows -- `mem0` — основной семантический провайдер -- `localjson` — встроенный провайдер для тестов и демо -- `claude_memory` — консервативный файловый адаптер для поверхностей памяти Claude Code -- `mempalace` — экспериментальный локальный семантический провайдер на базе коллекции MemPalace, принадлежащей AgentMemory -- контракт провайдера, реестр операций, транспортные адаптеры и политика рантайма реализованы -- диагностика и обнаружение областей (scope) входят в текущую поверхность продукта +### Области и записи -## Текущие ограничения +Воспоминание принадлежит **области (scope)**: `user_id`, `agent_id`, `run_id` или их комбинации. Провайдеры заявляют, нужна ли область (`mem0` требует её для list и search; `localjson` — нет). Каждый провайдер возвращает одну и ту же нормализованную `MemoryRecord` (`id`, текст, `metadata` — всегда словарь, `provider` — всегда заполнен, необязательные данные провайдера только в `raw`), поэтому клиенты никогда не видят нативные формы бэкенда. Неподдерживаемые опции завершаются типизированными ошибками (`ProviderCapabilityError`, `ProviderScopeRequiredError`, `MemoryNotFoundError`, `ProviderUnavailableError`, `ProviderValidationError`, `ProviderConfigurationError` и `ProviderIdentityError` для проверки идентичности), а исключения бэкенда наружу не пробрасываются. -AgentMemory пригоден как локальный рантайм общей памяти, но это всё ещё публичная альфа. Актуальный индекс рисков и багов находится в [Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md). +AgentMemory ведёт собственный **реестр областей** (инвентарь, принадлежащий AgentMemory, который читает `list-scopes`). Источником истины остаётся основное хранилище провайдера; сбой синхронизации реестра помечает провайдера как деградировавшего, а не выдаёт успешную запись за неудачную, и `agentmemory rebuild-scope-registry` это чинит. -Важные текущие ограничения: +### 14 операций -- TTL существует как опциональная поддержка истечения. Это метаданные, управляемые вызывающей стороной, а не автоматическая классификация на краткосрочную и долгосрочную память. Провайдерам с нарушенной синхронизацией реестра областей может потребоваться `rebuild-scope-registry`, прежде чем TTL-очистку можно считать полной. -- `mem0` использует безопасный откат к одной странице для пагинации, пока не реализована безопасная для бэкенда стратегия курсоров. -- Дрейф внешней сети в Compose v2 смягчается скриптом `deploy/redeploy.sh`, но первопричина остаётся вне этого репозитория. +Описаны один раз в реестре операций ([operations.py](agentmemory/runtime/operations.py)) и доступны как MCP-инструменты с префиксом `memory_`: + +| Операция | MCP-инструмент | Что делает | +|---|---|---| +| `health` | `memory_health` | Информация о рантайме и провайдере | +| `add` | `memory_add` | Сохранить воспоминание (дословно по умолчанию; `infer`, `dedup`, метаданные TTL — opt-in) | +| `get` / `update` / `delete` | `memory_get` / `memory_update` / `memory_delete` | Работают по id записи; доступность зависит от возможностей провайдера | +| `search` / `search_page` | `memory_search` / `memory_search_page` | Семантический или текстовый поиск, при необходимости одна страница по курсору | +| `list` / `list_page` | `memory_list` / `memory_list_page` | Просмотр записей в области | +| `list_scopes` / `list_scopes_page` | `memory_list_scopes` / `memory_list_scopes_page` | Известные области user, agent и run | +| `export` / `import` | `memory_export` / `memory_import` | JSONL, не привязанный к провайдеру | +| `reconcile` | `memory_reconcile` | Проверка только на чтение: вероятные конфликтующие воспоминания | -## Ключевое проектное решение для Mem0 +### Слои + +Рантайм многослойный: клиенты, затем интерфейсы (CLI, HTTP, stdio MCP, интерактивная оболочка, браузерный интерфейс), затем ядро рантайма (реестр, адаптеры, валидация, формирование ошибок, маршрутизация, диагностика), затем контракт провайдера, затем адаптеры провайдеров, затем хранилище бэкенда. Поведение, специфичное для бэкенда, заканчивается на границе провайдера. См. [Architecture](docs/ARCHITECTURE.md) и [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md). + +### Ключевое проектное решение для Mem0 `mem0` в этом проекте использует локальное встроенное хранилище, а у локальных встроенных бэкендов бывают ограничения на процессы и блокировки. @@ -234,7 +334,49 @@ AgentMemory решает это, давая провайдеру явную тр Это один из самых наглядных примеров того, зачем нужен слой рантайма памяти, даже когда бэкенд по-прежнему `mem0`. -## Основные команды +На практике: `mem0` заявляет политику `owner_process_proxy`. Когда команде CLI или stdio MCP-серверу нужен бэкенд, они убеждаются, что локальный API запущен (при необходимости запускают его под межпроцессной блокировкой), и пересылают вызов по HTTP, включая API-токен, если он настроен. Провайдеры с транспортом `direct` (`localjson`, `claude_memory`, `mempalace`) открываются в том же процессе. + +## Интерфейсы + +### CLI + +```powershell +.\.venv\Scripts\agentmemory.exe --help +``` + +Запуск `agentmemory` без аргументов открывает интерактивную оболочку с первичной настройкой и slash-командами (`/help`, `/install`, `/configure`, `/provider`, `/doctor`, `/start`, `/stop`, `/ui`, `/mcp`, `/status`, `/clients`, `/snippets`, `/exit`). Подкоманды удобны для автоматизации. Группы: + +| Группа | Команды | +|---|---| +| Настройка | `install`, `configure`, `profile-list`, `profile-create`, `profile-use` | +| Рантайм | `start-api`, `stop-api`, `doctor`, `mcp-smoke`, `snippets` | +| Клиенты | `connect-clients`, `disconnect-clients`, `status-clients`, `doctor-clients` | +| Данные | `list-scopes`, `export-memories`, `import-memories`, `reconcile-memories`, `rebuild-scope-registry` | +| Провайдеры | `provider-certify` | + +Повседневные операции с памятью (add, search, list, get, update, delete, health, страницы) находятся в CLI данных: `python -m agentmemory.ops_cli <команда>`; например, `add --message "..." --user-id u1` и `search "запрос" --user-id u1 --no-rerank`. `add` сохраняет дословно, если вы не передали `--infer`. + +### HTTP API + +Обслуживается процессом локального API (по умолчанию `127.0.0.1:8765`; `start-api` выбирает свободный порт, если настроенный занят). Маршруты в [api.py](agentmemory/api.py): + +| Маршрут | Назначение | +|---|---| +| `GET /health` | Проверка живости (открыт); полная диагностика для авторизованных | +| `GET /metrics` | Метрики в текстовом формате Prometheus (для авторизованных) | +| `POST /add`, `/search`, `/search/page`, `/update` | Операции с памятью | +| `GET /memories`, `/memories/page`, `/memories/`; `DELETE /memories/` | Чтение и удаление | +| `GET/PATCH/DELETE /admin/memories...`, `POST /admin/memories//pin`, `GET /admin/stats`, `/admin/stats/operations`, `/admin/scopes`, `/admin/scopes/page`, `/admin/clients` | Операторский интерфейс, которым пользуется браузерный UI | +| `POST /mcp` | MCP поверх HTTP (JSON-RPC, одиночные и пакетные запросы) | +| `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/oauth/authorize`, `/oauth/token`, `/register` | OAuth 2.1 и Dynamic Client Registration | + +Без настроенного токена и без OAuth API открыт (рассчитан на чисто локальное использование). При `AGENTMEMORY_API_TOKEN` или включённом OAuth всё, кроме `/health`, документов discovery и конечных точек OAuth authorize/token/register, требует bearer-учётных данных. Ответы с ошибками используют типизированные значения `error_type`, сопоставленные со статусами HTTP. + +### MCP + +`agentmemory-mcp` (через `scripts/run-agentmemory-mcp.ps1` или `.sh`) запускает stdio MCP-сервер, поддерживающий версии протокола `2025-06-18` и `2024-11-05`, отдаёт список из 14 инструментов и проверяет аргументы каждого вызова по входной схеме инструмента. `agentmemory mcp-smoke` выполняет самопроверку initialize / tools-list / tools-call. Тот же набор инструментов отдаётся по HTTP на `POST /mcp` для удалённых клиентов. + +### Основные команды ```powershell .\.venv\Scripts\agentmemory.exe --help @@ -251,7 +393,7 @@ AgentMemory решает это, давая провайдеру явную тр `agentmemory snippets` печатает готовые сниппеты для Claude Code и Gemini CLI. -## Точки входа в корне репозитория +### Точки входа в корне репозитория Для тех, кому нужен один очевидный запуск из корня репозитория, AgentMemory также поставляет тонкие обёртки для Windows и POSIX-оболочек. @@ -275,6 +417,55 @@ macOS / Linux: Эти обёртки делегируют работу поддерживаемым скриптам в `scripts/`, так что корень остаётся удобным, а операционная реализация не уезжает из `scripts/`. +## Провайдеры + +| Провайдер | Статус | Семантический поиск | Текстовый поиск | Update | Delete | Пагинация | Область нужна для list/search | Транспорт | +|---|---|---|---|---|---|---|---|---| +| `mem0` | сертифицирован (политика: certified with skips) | да (rerank поддерживается) | нет | да | да | откат к одной странице | да | прокси процесса-владельца | +| `localjson` | сертифицирован | нет | да | да | да | да | нет | напрямую | +| `claude_memory` | экспериментальный | нет | да | нет | нет | нет | нет | напрямую | +| `mempalace` | экспериментальный | да | нет | нет | да | нет | нет | напрямую | + +Таблица отражает заявленные `capabilities()` и метаданные реестра каждого провайдера в коде. Сертификация означает, что провайдер проходит общий набор контрактных тестов; это не утверждение о качестве поиска. + +### Mem0 + +Используйте `mem0`, когда нужны: + +- семантический поиск +- извлечение и эмбеддинги через OpenRouter +- основной продакшен-путь этого репозитория + +Примечания: + +- требуется `OPENROUTER_API_KEY` +- в этом репозитории использует транспорт через прокси процесса-владельца +- является текущим провайдером по умолчанию (быстрый старт выше намеренно начинается с `localjson`) +- хранит данные во встроенном хранилище в каталоге данных рантайма; настройки моделей по умолчанию используют модели, размещённые в OpenRouter (меняются флагами `configure`, например `--embedding-model`) +- пакет жёстко фиксирует `mem0ai==1.0.10` + +### Local JSON + +Используйте `localjson`, когда нужны: + +- ноль внешних API-зависимостей +- простой встроенный бэкенд для тестов и демо +- провайдер, который можно просмотреть на диске (один JSON-файл, по умолчанию `data/localjson-memories.json`, меняется через `--storage-path`) + +### Claude Memory (экспериментально) + +`claude_memory` — консервативный файловый адаптер для поверхностей памяти Claude Code: он умеет читать пользовательскую память, память проекта и авто-память (каждую можно отключить через `--no-user-memory` / `--no-auto-memory`), а пишет только в каталог, принадлежащий AgentMemory (по умолчанию `.claude/rules/agentmemory` в корне Git проекта). Update, delete и инвентаризацию областей он не заявляет. + +### MemPalace (экспериментально) + +`mempalace` — локальный семантический провайдер на базе коллекции MemPalace, принадлежащей AgentMemory (`--palace-path`, `--palace-id`, `--collection-name`). Его зависимость (`mempalace==3.3.5`) ставится вместе с провайдером; update и фильтры он не заявляет. + +Подробности и правила адаптеров: [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md), [Future Memory Providers](docs/future-memory-providers/README.md). + +## Подключение клиентов + +`agentmemory connect-clients` находит поддерживаемые клиенты и добавляет AgentMemory как MCP-сервер: Codex, Claude Code, Claude Desktop, Gemini CLI, Qwen CLI, Cursor, VS Code / Copilot, Roo Code, KiloCode и Cline. Если конфигурация клиента — файл, прежняя версия сохраняется в `data/backups/client-configs`. `disconnect-clients` убирает подключение; `status-clients` и `doctor-clients` показывают обнаружение, состояние конфигурации и здоровье локального MCP в форматах `--json`, `--table` или `--compact` (стабильные коды выхода для скриптов). Процесс ориентирован сначала на Windows; сам рантайм работает и на Linux и macOS, но автоподключение клиентов на этих платформах проверено меньше. Для клиентов вне списка используйте `agentmemory snippets` или направьте любой MCP-клиент на `scripts/run-agentmemory-mcp.ps1` / `.sh`. + ## Удалённые MCP-коннекторы (Claude.ai, ChatGPT) Когда AgentMemory опубликован по публичному URL, он говорит по MCP поверх HTTP на `POST /mcp` и поддерживает OAuth 2.1 с Dynamic Client Registration (RFC 7591). Хостируемые MCP-клиенты вроде Custom Connectors в Claude.ai или ChatGPT находят сервер и регистрируются сами, без выданного оператором client_id. @@ -295,6 +486,37 @@ macOS / Linux: - `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` — лимит на IP для /register (по умолчанию 20). - `AGENTMEMORY_PUBLIC_URL` — канонический https-URL, который сервер должен сообщать в OAuth discovery. +Токены доступа живут 7 дней, refresh-токены — 30 дней; обновление выдаёт новую пару и аннулирует старый refresh-токен. Зарегистрированные клиенты хранятся с хешированными секретами. Прочитайте [Безопасность и идентичность](#безопасность-и-идентичность), прежде чем открывать сервер наружу: шаг авторизации одобряет автоматически, а входа пользователя нет. + +## Безопасность и идентичность + +- **По умолчанию локально.** API слушает `127.0.0.1`; без токена и без OAuth он принимает анонимные локальные вызовы. Задайте `AGENTMEMORY_API_TOKEN` (корневой `docker-compose.yml` не запустится без него), прежде чем привязывать сервер к чему-либо, кроме loopback. +- **Защитные меры.** Лимит частоты на каждые учётные данные по схеме token bucket (по умолчанию 60 в минуту, `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`), лимит на IP для `/register`, ограничение размера тела запроса (по умолчанию 16 МиБ, `AGENTMEMORY_MAX_BODY_BYTES`) и `AGENTMEMORY_DISABLE_UI=1`, чтобы отключить браузерный интерфейс на удалённых развёртываниях. +- **Нет аутентификации конечных пользователей.** В AgentMemory нет входа. По умолчанию `user_id` берётся из тела запроса, поэтому любые действительные учётные данные могут назвать любую область. +- **Привязка идентичности (opt-in).** При `AGENTMEMORY_ENFORCE_AUTH_USER_ID=1` и учётных данных, несущих привязанную идентичность (задаётся для каждого клиента OAuth, например `AGENTMEMORY_OAUTH_BOUND_USER_ID`), совпадающий `user_id` проходит, отсутствующий подставляется, а другой отклоняется с `ProviderIdentityError` (HTTP 403). Операции, охватывающие всё хранилище, и маршруты `/admin/*` для привязанных учётных данных закрыты. Проверка находится в единственной обёртке, через которую проходит каждая операция, поэтому HTTP, MCP и CLI делят одну реализацию. +- **Чего привязка не даёт.** Это не изоляция арендаторов: она настолько надёжна, насколько надёжен тот, кто выдал токен; она теряет силу, пока включена динамическая регистрация и существуют непривязанные учётные данные; её нужно включать в том процессе, с которым говорят клиенты; `agent_id` и `run_id` не привязываются; провайдеры не разделяют хранилище. Сначала прочитайте [Auth identity binding](docs/AUTH_IDENTITY_BINDING.md) и [SECURITY.md](SECURITY.md). + +## Семантика памяти + +AgentMemory последовательно исполняет заявленную семантику; он не угадывает намерения ([Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md)). + +- **`infer` по умолчанию выключен.** `memory_add` сохраняет текст дословно. При `infer=true` LLM провайдера может извлечь, переписать или разбить входной текст (один вызов LLM на запись); ответ сообщает об этом (`transformed`, `original_text`, `stored_text`), а дополнительные записи появляются в `additional_records`. CLI делает так же: `--infer` — явное согласие. +- **Дедупликация при добавлении (opt-in).** `dedup=true` сначала выполняет семантический поиск в той же области и возвращает найденную существующую запись (`dedup_hit`) вместо вставки дубликата. Нужна область и провайдер с семантическим поиском; порог сходства пока не настраивается пользователем. +- **TTL — opt-in и по умолчанию выключен.** `metadata.ttl_seconds` или `metadata.expires_at` отклоняются, пока оператор не задаст `AGENTMEMORY_ALLOW_TTL=1`. Если включено, истёкшие записи скрываются при чтении, а фоновый уборщик (по умолчанию раз в 10 минут, `AGENTMEMORY_TTL_SWEEP_MINUTES`) удаляет их безвозвратно; ошибка в единицах измерения может уничтожить запись навсегда, поэтому по умолчанию он выключен. TTL — это метаданные, управляемые вызывающей стороной, а не автоматическая классификация на краткосрочную и долгосрочную память. +- **Предупреждения об устаревании.** Если `metadata.stale_after` записи уже прошло, результаты поиска содержат `stale_warning` (запись не скрывается), чтобы вызывающая сторона перепроверила факты, привязанные ко времени. +- **Reconcile.** `reconcile-memories` / `memory_reconcile` — проверка гигиены только на чтение, которая перечисляет вероятно конфликтующие пары воспоминаний в области. Она не изменяет хранилище и является ранней эвристикой, а не гарантией. + +## Экспорт, импорт и гигиена + +- `agentmemory export-memories <путь>` и `import-memories <путь>` (а также MCP `memory_export` / `memory_import`) переносят воспоминания в виде JSONL, не привязанного к провайдеру, обходя инвентарь областей. Импорт воспроизводит записи через `add` с `infer=false` ради точного круговорота. Путь разрешается на машине, выполняющей операцию, поэтому при удалённом MCP-подключении это путь на сервере. Экспорт и импорт закрыты для учётных данных с привязанной идентичностью. +- `rebuild-scope-registry` заново заполняет инвентарь областей для активного провайдера. +- Запись файлов рантайма (состояние, реестры, токены) идёт через вспомогательные функции атомарной записи. + +## Профили и doctor + +- **Профили.** `profile-list`, `profile-create <имя> [--copy-from ...]` и `profile-use <имя>` управляют именованными профилями рантайма (например, `default`, `staging`); `AGENTMEMORY_PROFILE` выбирает профиль для процесса, а `AGENTMEMORY_HOME` указывает корень рантайма. +- **`doctor`.** Проверяет venv, конфигурацию, наличие ключей и состояние, сообщает активный профиль, id рантайма, версию конфигурации, состояние рантайма API и версию контракта провайдера, с подсказками по провайдеру. Отсутствующий `.env` — только информация, чтобы путь с `localjson` оставался тихим. `start-api` отличает устаревший PID от чужого процесса на порту. + ## Браузерный интерфейс Локальный API также отдаёт браузерный интерфейс по адресу: @@ -313,52 +535,58 @@ http://127.0.0.1:8765/ - удаление малоценных воспоминаний - сводка по статусу клиентов -## Провайдеры +Интерфейс — одностраничное приложение на Vue 3 в [`web/`](web/): представления «таблица» и «лента», инспектор, массовый выбор, диалог добавления воспоминания, фильтры по областям, страница `/me` с воспоминаниями одного пользователя, палитра команд (`Ctrl/Cmd+K` или `/`), горячие клавиши (нажмите `?` в интерфейсе) и строка статуса с живыми счётчиками операций. -### Mem0 +**Шаг сборки.** Собранный бандл в репозиторий не закоммичен. При запуске из исходников соберите его один раз, иначе `/` отвечает 503 с пояснением, что бандл интерфейса не собран: -Используйте `mem0`, когда нужны: +```sh +cd web && npm install && npm run build +``` -- семантический поиск -- извлечение и эмбеддинги через OpenRouter -- основной продакшен-путь этого репозитория +Docker-образ собирает его сам. Задайте `AGENTMEMORY_DISABLE_UI=1`, чтобы отключить интерфейс. -Примечания: +## Эксплуатация и развёртывание -- требуется `OPENROUTER_API_KEY` -- в этом репозитории использует транспорт через прокси процесса-владельца -- является текущим провайдером по умолчанию +### Метрики -### Local JSON +API собирает в памяти счётчики, гистограммы задержек и оценку расхода токенов и стоимости OpenRouter; они отдаются в текстовом формате Prometheus на `GET /metrics` (для авторизованных) и в JSON на `/admin/stats/operations`. Данные живут в памяти; перезапуск очищает историю. -Используйте `localjson`, когда нужны: +### Docker и развёртывание -- ноль внешних API-зависимостей -- простой встроенный бэкенд для тестов и демо -- провайдер, который можно просмотреть на диске +- [Dockerfile](Dockerfile) собирает веб-консоль на первом этапе и запускает API (`python -m agentmemory.api`) на втором. +- Корневой [docker-compose.yml](docker-compose.yml) требует `AGENTMEMORY_API_TOKEN` и по умолчанию публикует порт на `127.0.0.1` (`AGENTMEMORY_BIND_ADDR`, `AGENTMEMORY_PUBLISHED_PORT`). +- [deploy/](deploy/) и [docs/DEPLOY.md](docs/DEPLOY.md) описывают развёртывание за обратным прокси (Traefik) как удалённый MCP плюс HTTP, со скриптом повторного развёртывания, обходящим дрейф внешней сети Compose v2 (см. [Текущие ограничения](#текущие-ограничения)), и скриптом резервного копирования. -## Карта документации +## Справочник -- [Start Here](docs/START_HERE.md) -- [Why AgentMemory Exists](docs/WHY_AGENTMEMORY.md) -- [Mem0 vs AgentMemory](docs/MEM0_VS_AGENTMEMORY.md) -- [What AgentMemory Adds To Mem0](docs/MEM0_WITH_AGENTMEMORY_VALUE.md) -- [What AgentMemory Actually Adds](docs/WHAT_AGENTMEMORY_ACTUALLY_ADDS.md) -- [Use Cases](docs/USE_CASES.md) -- [Architecture](docs/ARCHITECTURE.md) -- [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md) -- [Backlog / Current Limitations](docs/planning/BACKLOG.md) -- [Positioning Assets](docs/POSITIONING.md) -- [Roadmap](docs/planning/ROADMAP.md) -- [Contributing](CONTRIBUTING.md) -- [Security](SECURITY.md) -- [Support](SUPPORT.md) +### Переменные окружения -## Примеры +| Переменная | Назначение | +|---|---| +| `OPENROUTER_API_KEY` | Ключ для провайдера `mem0` | +| `AGENTMEMORY_API_HOST`, `AGENTMEMORY_API_PORT` | Адрес и порт API (по умолчанию `127.0.0.1:8765`) | +| `AGENTMEMORY_API_TOKEN` | Заранее выданный bearer для HTTP и `/mcp` | +| `AGENTMEMORY_PUBLIC_URL` | Публичный базовый URL в OAuth discovery | +| `AGENTMEMORY_OAUTH_CLIENT_ID`, `AGENTMEMORY_OAUTH_CLIENT_SECRET`, `AGENTMEMORY_OAUTH_BOUND_USER_ID` | Статический клиент OAuth и его привязанная идентичность | +| `AGENTMEMORY_OAUTH_DISABLE_DCR`, `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` | Переключатель динамической регистрации и её лимит | +| `AGENTMEMORY_OAUTH_STORE`, `AGENTMEMORY_OAUTH_TOKEN_STORE` | Переопределение путей хранилищ OAuth | +| `AGENTMEMORY_ENFORCE_AUTH_USER_ID` | Привязка идентичности (opt-in) | +| `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`, `AGENTMEMORY_MAX_BODY_BYTES` | Лимит частоты и ограничение размера тела | +| `AGENTMEMORY_DISABLE_UI` | Отключить браузерный интерфейс | +| `AGENTMEMORY_ALLOW_TTL`, `AGENTMEMORY_TTL_SWEEP_MINUTES` | Включить TTL и настроить уборщика | +| `AGENTMEMORY_PROFILE`, `AGENTMEMORY_HOME` | Выбор профиля и корня рантайма | +| `AGENTMEMORY_BIND_ADDR`, `AGENTMEMORY_PUBLISHED_PORT` | Адрес и порт публикации в Docker Compose | +| `AGENTMEMORY_*_MCP_CONFIG`, `AGENTMEMORY_CLAUDE_DESKTOP_CONFIG` | Переопределение расположения файлов конфигурации клиентов (например, VS Code, Roo, Kilo, Cline, Claude Desktop) | -- [HTTP Python Roundtrip](examples/http_python_roundtrip.py) -- [Shared Runtime Demo](examples/shared-runtime-demo.md) -- [MCP Demo](examples/mcp-demo.md) +`AGENTMEMORY_OWNER_PROCESS` выставляет сам рантайм для процесса-владельца; вручную его задавать не нужно. + +### Файлы на диске + +В корне рантайма: `.env`, `agentmemory.config.json`, `data/` (данные провайдера, реестр областей, файлы PID/состояния API, `oauth_clients.json`, `oauth_tokens.json`, резервные копии конфигураций клиентов). Всё это только локальное. + +### Структура репозитория + +`agentmemory/` (пакет: `providers/`, `runtime/`, `certification/`, CLI, API, MCP, OAuth, клиенты), `web/` (консоль на Vue), `scripts/` и корневые лаунчеры, `deploy/`, `docs/`, `examples/`, `snippets/`, `tests/`. ## Проверка @@ -371,9 +599,11 @@ http://127.0.0.1:8765/ .\.venv\Scripts\python.exe -m agentmemory.ops_cli list-scopes --limit 20 ``` +Непрерывная интеграция запускает модульные тесты на Ubuntu и Windows (Python 3.13) и отдельную проверку политики сертификации провайдеров. + ## Сертификация провайдеров -AgentMemory рассматривает провайдеры как адаптерные слои за одним общим контрактом. +AgentMemory рассматривает провайдеры как адаптерные слои за одним общим контрактом. Провайдер считается сертифицированным, только если он возвращает нормализованные данные, соблюдает заявленные возможности, выбрасывает типизированные ошибки и проходит общий набор контрактных тестов; иначе он экспериментальный. Статусы в реестре: `certified`, `provisional`, `experimental` и `test-only` (фиктивный провайдер в памяти доказывает, что набор тестов не зависит от бэкенда). Полезные ссылки: @@ -389,6 +619,77 @@ AgentMemory рассматривает провайдеры как адапте .\.venv\Scripts\provider-certify.exe localjson --json --run-tests --summary-only ``` +`provider-certify-ci --json` проверяет, что каждый провайдер по-прежнему соответствует ожидаемому статусу политики (`localjson`: certified; `mem0`: certified with skips). + +## Устранение неполадок + +- **`agentmemory` не находится.** Используйте явные пути `.venv`, как в быстром старте. +- **API не стартует или порт занят.** Запустите `doctor` и прочитайте блокирующие ошибки; `start-api` выбирает свободный порт и обновляет конфигурацию рантайма, а также отличает устаревший PID от чужого слушателя. +- **`mem0` не работает.** Вернитесь к `localjson`; убедитесь, что задан `OPENROUTER_API_KEY`. Некоторые хосты не достают до бэкендов эмбеддингов; симптом и обходной путь через прокси-сайдкар описаны в `docs/DEPLOY.md`. +- **Браузерный интерфейс отвечает 503.** Соберите бандл: `cd web && npm install && npm run build`. +- **Удалённый клиент получает 401.** Передавайте `Authorization: Bearer <токен>` или пройдите поток OAuth; `/health` остаётся открытым. +- **`add` с TTL отклонён.** TTL по умолчанию выключен; см. [Семантика памяти](#семантика-памяти). +- **Область выглядит пустой или счётчики не сходятся.** Запустите `agentmemory rebuild-scope-registry`. + +## Текущий статус + +- `public alpha` (публичная альфа) +- локальный продукт (local-first) +- ядро рантайма работает на Windows, Linux и ожидаемо на macOS +- процесс интеграции с клиентами сначала ориентирован на Windows +- `mem0` — основной семантический провайдер +- `localjson` — встроенный провайдер для тестов и демо +- `claude_memory` — консервативный файловый адаптер для поверхностей памяти Claude Code +- `mempalace` — экспериментальный локальный семантический провайдер на базе коллекции MemPalace, принадлежащей AgentMemory +- контракт провайдера, реестр операций, транспортные адаптеры и политика рантайма реализованы +- диагностика и обнаружение областей (scope) входят в текущую поверхность продукта + +## Текущие ограничения + +AgentMemory пригоден как локальный рантайм общей памяти, но это всё ещё публичная альфа. Актуальный индекс рисков и багов находится в [Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md). + +Важные текущие ограничения: + +- TTL существует как опциональная поддержка истечения. Это метаданные, управляемые вызывающей стороной, а не автоматическая классификация на краткосрочную и долгосрочную память. Провайдерам с нарушенной синхронизацией реестра областей может потребоваться `rebuild-scope-registry`, прежде чем TTL-очистку можно считать полной. +- `mem0` использует безопасный откат к одной странице для пагинации, пока не реализована безопасная для бэкенда стратегия курсоров. +- Дрейф внешней сети в Compose v2 смягчается скриптом `deploy/redeploy.sh`, но первопричина остаётся вне этого репозитория. + +Также стоит знать (из бэклога и документов по безопасности): + +- `infer` по умолчанию выключен; при `infer=true` содержимое может быть переписано LLM провайдера. +- Динамическая регистрация и автоматически одобряющий шаг авторизации означают, что доступный по сети сервер может выдать непривязанные токены; привязка идентичности имеет смысл только при отключённом DCR и привязке каждого клиента. Это не изоляция арендаторов. +- Уборщик удаляет истёкшие записи безвозвратно (окна восстановления пока нет); мягкое удаление — пункт бэклога. +- Метрики хранятся в памяти и сбрасываются при перезапуске. +- Автоподключение клиентов сначала ориентировано на Windows. +- Среди открытых пунктов бэклога с приоритетом P1 — идентичность для клиентов OAuth, созданных через DCR, и «пинг мёртвой руки» для резервного копирования. + +## Карта документации + +- [Start Here](docs/START_HERE.md) +- [Why AgentMemory Exists](docs/WHY_AGENTMEMORY.md) +- [Mem0 vs AgentMemory](docs/MEM0_VS_AGENTMEMORY.md) +- [What AgentMemory Adds To Mem0](docs/MEM0_WITH_AGENTMEMORY_VALUE.md) +- [What AgentMemory Actually Adds](docs/WHAT_AGENTMEMORY_ACTUALLY_ADDS.md) +- [Use Cases](docs/USE_CASES.md) +- [Architecture](docs/ARCHITECTURE.md) +- [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md) +- [Auth identity binding](docs/AUTH_IDENTITY_BINDING.md) +- [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md) и [Provider Certification](docs/PROVIDER_CERTIFICATION.md) +- [Deploy](docs/DEPLOY.md) +- [Backlog / Current Limitations](docs/planning/BACKLOG.md) +- [Positioning Assets](docs/POSITIONING.md) +- [Roadmap](docs/planning/ROADMAP.md) +- [Changelog](CHANGELOG.md) +- [Contributing](CONTRIBUTING.md) +- [Security](SECURITY.md) +- [Support](SUPPORT.md) + +## Примеры + +- [HTTP Python Roundtrip](examples/http_python_roundtrip.py) +- [Shared Runtime Demo](examples/shared-runtime-demo.md) +- [MCP Demo](examples/mcp-demo.md) + ## Лицензия [MIT](LICENSE). From 79bbf4db72db73364d8faa2c181b630db3182f29 Mon Sep 17 00:00:00 2001 From: Andrew_Moryakov Date: Thu, 1 Oct 2026 14:21:54 +0300 Subject: [PATCH 2/2] docs(readme): address review on #3 - Quick start next steps: bare `agentmemory` commands only work from the activated .venv; add activation / explicit-path note (header teaser, Next steps, troubleshooting), EN + RU. - claude_memory: project memory (CLAUDE.md walk-up, .claude/CLAUDE.md, .claude/rules/**) is always read; only user-level and auto memory are switchable. EN + RU. - Auth rule: the browser UI's static routes (/, /me, /assets/*, root files) are served without a credential; narrow the "everything requires a bearer" claim and point remote deployments to AGENTMEMORY_DISABLE_UI=1. HTTP API, Guards, Browser UI sections, EN + RU. --- README.md | 14 ++++++++++---- README.ru.md | 14 ++++++++++---- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ce612c4..123d2a7 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ agentmemory configure --provider localjson # no API keys needed agentmemory start-api # one local runtime, several client surfaces ``` +Run these from the project's virtual environment (activate it, or call `.\.venv\Scripts\agentmemory.exe` / `./.venv/bin/agentmemory`); the [quick start](#quickstart) has the exact steps. + AgentMemory is a shared local memory runtime for AI clients and agents. It sits above a memory backend (a *provider*: `mem0`, a built-in JSON store, and two experimental adapters) and exposes **one stable set of 14 memory operations** through a CLI, a local HTTP API and an MCP server, so what one tool saves, another can recall. Around that core it adds: an owner-process transport for backends that cannot be opened by many processes at once; one-command wiring into ten AI clients and editors; a remote MCP endpoint with bearer-token and OAuth 2.1 (Dynamic Client Registration) support; JSONL export/import; opt-in memory semantics (dedup, TTL, stale warnings, a read-only conflict check); a `doctor` that explains what is wrong; a browser console; metrics; Docker deployment files; and a provider certification harness for adding new backends. It is a **public alpha** (version 0.1.0, local-first, not hardened for hostile multi-tenant or open-network use). See [Current Status](#current-status) and [Current Limitations](#current-limitations) before you depend on it. @@ -237,6 +239,8 @@ What success looks like: ### Next steps +The quick start installs AgentMemory only into `.venv`, which it never activates. Throughout the rest of this README `agentmemory ...` is shorthand for that environment's executable: either activate the environment once per shell (`.\.venv\Scripts\Activate.ps1` on Windows, `source .venv/bin/activate` on macOS / Linux) or call it by path (`.\.venv\Scripts\agentmemory.exe`, `./.venv/bin/agentmemory`). Otherwise the bare command is not found. + - Connect your AI clients: `agentmemory connect-clients`, then `agentmemory status-clients --compact` ([Client wiring](#client-wiring)). - Look at what was stored in the browser console ([Browser UI](#browser-ui); from source it needs a one-time `npm install && npm run build` in `web/`). - Run the MCP self-test: `agentmemory mcp-smoke`. @@ -370,7 +374,7 @@ Served by the local API process (default `127.0.0.1:8765`; `start-api` picks a f | `POST /mcp` | MCP over HTTP (JSON-RPC, single or batch) | | `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/oauth/authorize`, `/oauth/token`, `/register` | OAuth 2.1 and Dynamic Client Registration | -Without a configured token and without OAuth, the API is open (intended for local-only use). With `AGENTMEMORY_API_TOKEN` or OAuth enabled, everything except `/health`, the discovery documents and the OAuth authorize/token/register endpoints requires a bearer credential. Error responses use typed `error_type` values mapped to HTTP statuses. +Without a configured token and without OAuth, the API is open (intended for local-only use). With `AGENTMEMORY_API_TOKEN` or OAuth enabled, every API and data route requires a bearer credential except `/health` (unauthenticated callers get only `{"ok": true}`), the OAuth discovery documents and the OAuth authorize/token/register endpoints. The browser UI's static files (`/`, `/me`, `/assets/*` and a few root files such as `/favicon.ico`) are also served without a credential; only the data calls the UI makes are protected. On a remote deployment set `AGENTMEMORY_DISABLE_UI=1`. Error responses use typed `error_type` values mapped to HTTP statuses. ### MCP @@ -454,7 +458,7 @@ Use `localjson` when you want: ### Claude Memory (experimental) -`claude_memory` is a conservative file-backed adapter over Claude Code memory surfaces: it can read user-level memory, project memory and auto-memory (each switchable with `--no-user-memory` / `--no-auto-memory`), and writes only into an AgentMemory-owned directory (by default `.claude/rules/agentmemory` under the project's Git root). It declares no update, no delete and no scope inventory. +`claude_memory` is a conservative file-backed adapter over Claude Code memory surfaces: it always reads project memory (`CLAUDE.md` and `CLAUDE.local.md` from the start path up to the project root, `.claude/CLAUDE.md` and `.claude/rules/**/*.md`; there is no option to turn that off), and it can also read user-level memory and auto-memory, each switchable with `--no-user-memory` / `--no-auto-memory`. It writes only into an AgentMemory-owned directory (by default `.claude/rules/agentmemory` under the project's Git root). It declares no update, no delete and no scope inventory. ### MemPalace (experimental) @@ -491,7 +495,7 @@ Access tokens last 7 days and refresh tokens 30 days; a refresh rotates the pair ## Security and identity - **Local by default.** The API binds `127.0.0.1`; with no token and no OAuth it accepts anonymous local calls. Set `AGENTMEMORY_API_TOKEN` (the root `docker-compose.yml` refuses to start without one) before binding to anything other than loopback. -- **Guards.** A per-credential token-bucket rate limit (default 60 per minute, `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`), a per-IP cap on `/register`, a request body cap (default 16 MiB, `AGENTMEMORY_MAX_BODY_BYTES`), and `AGENTMEMORY_DISABLE_UI=1` to turn the browser UI off on remote deployments. +- **Guards.** A per-credential token-bucket rate limit (default 60 per minute, `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`), a per-IP cap on `/register`, a request body cap (default 16 MiB, `AGENTMEMORY_MAX_BODY_BYTES`), and `AGENTMEMORY_DISABLE_UI=1` to turn the browser UI off on remote deployments (its static files are served without a credential even when a token is set; only the data calls behind them are protected). - **No end-user authentication.** AgentMemory has no login. By default `user_id` is taken from the request payload, so any valid credential can name any scope. - **Opt-in identity binding.** With `AGENTMEMORY_ENFORCE_AUTH_USER_ID=1` and a credential that carries a bound identity (configured per OAuth client, for example `AGENTMEMORY_OAUTH_BOUND_USER_ID`), a matching `user_id` passes, a missing one is filled in, and a different one is refused with `ProviderIdentityError` (HTTP 403). Operations that range over the whole store and the `/admin/*` routes are refused to a bound credential. The check lives in the single wrapper every operation passes through, so HTTP, MCP and CLI share it. - **What binding does not give you.** It is not tenant isolation: it is only as trustworthy as whatever issued the token; it is void while dynamic registration is enabled and unbound credentials exist; it must be set on the process clients talk to; `agent_id` and `run_id` are not bound; providers do not partition storage. Read [Auth identity binding](docs/AUTH_IDENTITY_BINDING.md) and [SECURITY.md](SECURITY.md) first. @@ -545,6 +549,8 @@ cd web && npm install && npm run build The Docker image builds it for you. Set `AGENTMEMORY_DISABLE_UI=1` to switch the UI off. +**Authentication.** With a token or OAuth configured, the data requests the UI makes (the `/admin/*` routes) need a bearer credential, but the static page and assets (`/`, `/me`, `/assets/*`, a few root files) are served without one. Do not rely on the token to hide the UI itself; on a remote deployment turn it off with `AGENTMEMORY_DISABLE_UI=1`. + ## Operations and deployment ### Metrics @@ -623,7 +629,7 @@ Quick helper commands: ## Troubleshooting -- **`agentmemory` not found.** Use the explicit `.venv` paths shown in the quick start. +- **`agentmemory` not found.** The command lives in `.venv`: activate the environment or use the explicit `.venv` paths shown in the quick start. - **API will not start or the port is busy.** Run `doctor` and read the blocking errors; `start-api` selects a free port and updates the runtime config, and distinguishes a stale PID from a foreign listener. - **`mem0` fails.** Go back to `localjson`; confirm `OPENROUTER_API_KEY` is set. Some hosts cannot reach the embedding backends; `docs/DEPLOY.md` describes the symptom and a proxy-sidecar workaround. - **Browser UI returns 503.** Build the bundle: `cd web && npm install && npm run build`. diff --git a/README.ru.md b/README.ru.md index 2e0269c..5efe7f4 100644 --- a/README.ru.md +++ b/README.ru.md @@ -16,6 +16,8 @@ agentmemory configure --provider localjson # API-ключи не нужны agentmemory start-api # один локальный рантайм, несколько клиентских интерфейсов ``` +Запускайте эти команды из виртуального окружения проекта (активируйте его или вызывайте `.\.venv\Scripts\agentmemory.exe` / `./.venv/bin/agentmemory`); точные шаги есть в [быстром старте](#quickstart). + AgentMemory — это общий локальный рантайм памяти для ИИ-клиентов и агентов. Он стоит над бэкендом памяти (*провайдером*: `mem0`, встроенное JSON-хранилище и два экспериментальных адаптера) и даёт **один стабильный набор из 14 операций памяти** через CLI, локальный HTTP API и MCP-сервер: то, что сохранил один инструмент, может вспомнить другой. Вокруг этого ядра он добавляет: транспорт через процесс-владелец для бэкендов, которые нельзя открывать из многих процессов сразу; подключение к десяти ИИ-клиентам и редакторам одной командой; удалённую MCP-точку с поддержкой bearer-токена и OAuth 2.1 (Dynamic Client Registration); экспорт и импорт в JSONL; опциональную семантику памяти (дедупликация, TTL, предупреждения об устаревании, проверка конфликтов только на чтение); `doctor`, объясняющий, что не так; браузерную консоль; метрики; файлы для развёртывания в Docker; и набор для сертификации провайдеров, чтобы добавлять новые бэкенды. Это **публичная альфа** (версия 0.1.0, local-first, не рассчитана на враждебные мультиарендные сценарии и открытую сеть). Прежде чем на неё опираться, прочитайте [Текущий статус](#текущий-статус) и [Текущие ограничения](#текущие-ограничения). @@ -237,6 +239,8 @@ python3 -m venv .venv ### Дальнейшие шаги +Быстрый старт ставит AgentMemory только в `.venv` и никогда не активирует его. Дальше в этом README `agentmemory ...` — сокращение для исполняемого файла из этого окружения: либо активируйте окружение один раз в каждой оболочке (`.\.venv\Scripts\Activate.ps1` в Windows, `source .venv/bin/activate` в macOS / Linux), либо вызывайте его по пути (`.\.venv\Scripts\agentmemory.exe`, `./.venv/bin/agentmemory`). Иначе голая команда не находится. + - Подключите ИИ-клиенты: `agentmemory connect-clients`, затем `agentmemory status-clients --compact` ([Подключение клиентов](#подключение-клиентов)). - Посмотрите, что сохранилось, в браузерной консоли ([Браузерный интерфейс](#браузерный-интерфейс); из исходников нужна разовая сборка `npm install && npm run build` в `web/`). - Запустите самопроверку MCP: `agentmemory mcp-smoke`. @@ -370,7 +374,7 @@ AgentMemory решает это, давая провайдеру явную тр | `POST /mcp` | MCP поверх HTTP (JSON-RPC, одиночные и пакетные запросы) | | `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/oauth/authorize`, `/oauth/token`, `/register` | OAuth 2.1 и Dynamic Client Registration | -Без настроенного токена и без OAuth API открыт (рассчитан на чисто локальное использование). При `AGENTMEMORY_API_TOKEN` или включённом OAuth всё, кроме `/health`, документов discovery и конечных точек OAuth authorize/token/register, требует bearer-учётных данных. Ответы с ошибками используют типизированные значения `error_type`, сопоставленные со статусами HTTP. +Без настроенного токена и без OAuth API открыт (рассчитан на чисто локальное использование). При `AGENTMEMORY_API_TOKEN` или включённом OAuth каждый API-маршрут и маршрут данных требует bearer-учётных данных, кроме `/health` (неавторизованный вызывающий получает только `{"ok": true}`), документов discovery OAuth и конечных точек OAuth authorize/token/register. Статические файлы браузерного интерфейса (`/`, `/me`, `/assets/*` и несколько корневых файлов вроде `/favicon.ico`) тоже отдаются без учётных данных; защищены только запросы за данными, которые делает интерфейс. На удалённом развёртывании задайте `AGENTMEMORY_DISABLE_UI=1`. Ответы с ошибками используют типизированные значения `error_type`, сопоставленные со статусами HTTP. ### MCP @@ -454,7 +458,7 @@ macOS / Linux: ### Claude Memory (экспериментально) -`claude_memory` — консервативный файловый адаптер для поверхностей памяти Claude Code: он умеет читать пользовательскую память, память проекта и авто-память (каждую можно отключить через `--no-user-memory` / `--no-auto-memory`), а пишет только в каталог, принадлежащий AgentMemory (по умолчанию `.claude/rules/agentmemory` в корне Git проекта). Update, delete и инвентаризацию областей он не заявляет. +`claude_memory` — консервативный файловый адаптер для поверхностей памяти Claude Code: он всегда читает память проекта (`CLAUDE.md` и `CLAUDE.local.md` от стартового пути до корня проекта, `.claude/CLAUDE.md` и `.claude/rules/**/*.md`; отключить это нельзя), а также может читать пользовательскую память и авто-память, каждую из которых можно отключить через `--no-user-memory` / `--no-auto-memory`. Пишет он только в каталог, принадлежащий AgentMemory (по умолчанию `.claude/rules/agentmemory` в корне Git проекта). Update, delete и инвентаризацию областей он не заявляет. ### MemPalace (экспериментально) @@ -491,7 +495,7 @@ macOS / Linux: ## Безопасность и идентичность - **По умолчанию локально.** API слушает `127.0.0.1`; без токена и без OAuth он принимает анонимные локальные вызовы. Задайте `AGENTMEMORY_API_TOKEN` (корневой `docker-compose.yml` не запустится без него), прежде чем привязывать сервер к чему-либо, кроме loopback. -- **Защитные меры.** Лимит частоты на каждые учётные данные по схеме token bucket (по умолчанию 60 в минуту, `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`), лимит на IP для `/register`, ограничение размера тела запроса (по умолчанию 16 МиБ, `AGENTMEMORY_MAX_BODY_BYTES`) и `AGENTMEMORY_DISABLE_UI=1`, чтобы отключить браузерный интерфейс на удалённых развёртываниях. +- **Защитные меры.** Лимит частоты на каждые учётные данные по схеме token bucket (по умолчанию 60 в минуту, `AGENTMEMORY_RATE_LIMIT_PER_MINUTE`), лимит на IP для `/register`, ограничение размера тела запроса (по умолчанию 16 МиБ, `AGENTMEMORY_MAX_BODY_BYTES`) и `AGENTMEMORY_DISABLE_UI=1`, чтобы отключить браузерный интерфейс на удалённых развёртываниях (его статические файлы отдаются без учётных данных, даже если задан токен; защищены только запросы за данными, которые за ними стоят). - **Нет аутентификации конечных пользователей.** В AgentMemory нет входа. По умолчанию `user_id` берётся из тела запроса, поэтому любые действительные учётные данные могут назвать любую область. - **Привязка идентичности (opt-in).** При `AGENTMEMORY_ENFORCE_AUTH_USER_ID=1` и учётных данных, несущих привязанную идентичность (задаётся для каждого клиента OAuth, например `AGENTMEMORY_OAUTH_BOUND_USER_ID`), совпадающий `user_id` проходит, отсутствующий подставляется, а другой отклоняется с `ProviderIdentityError` (HTTP 403). Операции, охватывающие всё хранилище, и маршруты `/admin/*` для привязанных учётных данных закрыты. Проверка находится в единственной обёртке, через которую проходит каждая операция, поэтому HTTP, MCP и CLI делят одну реализацию. - **Чего привязка не даёт.** Это не изоляция арендаторов: она настолько надёжна, насколько надёжен тот, кто выдал токен; она теряет силу, пока включена динамическая регистрация и существуют непривязанные учётные данные; её нужно включать в том процессе, с которым говорят клиенты; `agent_id` и `run_id` не привязываются; провайдеры не разделяют хранилище. Сначала прочитайте [Auth identity binding](docs/AUTH_IDENTITY_BINDING.md) и [SECURITY.md](SECURITY.md). @@ -545,6 +549,8 @@ cd web && npm install && npm run build Docker-образ собирает его сам. Задайте `AGENTMEMORY_DISABLE_UI=1`, чтобы отключить интерфейс. +**Аутентификация.** Если настроен токен или OAuth, запросы за данными, которые делает интерфейс (маршруты `/admin/*`), требуют bearer-учётных данных, но статическая страница и ресурсы (`/`, `/me`, `/assets/*`, несколько корневых файлов) отдаются без них. Не полагайтесь на токен как на способ скрыть сам интерфейс; на удалённом развёртывании отключите его через `AGENTMEMORY_DISABLE_UI=1`. + ## Эксплуатация и развёртывание ### Метрики @@ -623,7 +629,7 @@ AgentMemory рассматривает провайдеры как адапте ## Устранение неполадок -- **`agentmemory` не находится.** Используйте явные пути `.venv`, как в быстром старте. +- **`agentmemory` не находится.** Команда лежит в `.venv`: активируйте окружение или используйте явные пути `.venv`, как в быстром старте. - **API не стартует или порт занят.** Запустите `doctor` и прочитайте блокирующие ошибки; `start-api` выбирает свободный порт и обновляет конфигурацию рантайма, а также отличает устаревший PID от чужого слушателя. - **`mem0` не работает.** Вернитесь к `localjson`; убедитесь, что задан `OPENROUTER_API_KEY`. Некоторые хосты не достают до бэкендов эмбеддингов; симптом и обходной путь через прокси-сайдкар описаны в `docs/DEPLOY.md`. - **Браузерный интерфейс отвечает 503.** Соберите бандл: `cd web && npm install && npm run build`.