From 4cd229920821f220264e754415ed4eb558243b12 Mon Sep 17 00:00:00 2001 From: Ethan Date: Sun, 19 Apr 2026 20:31:54 -0700 Subject: [PATCH] docs: update API paths to /v1/memories/* prefix Core now serves memory routes under the /v1 version prefix. Update all quickstart, platform, and HTTP reference pages to match. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/api-reference/http/agents.md | 12 +++++----- docs/api-reference/http/audit.md | 10 ++++---- docs/api-reference/http/config.md | 4 ++-- .../http/consolidate-decay-cap.md | 10 ++++---- docs/api-reference/http/conventions.md | 6 ++--- docs/api-reference/http/ingest.md | 10 ++++---- docs/api-reference/http/lessons.md | 8 +++---- docs/api-reference/http/list-get-delete.md | 24 +++++++++---------- docs/api-reference/http/search.md | 12 +++++----- docs/platform/composition.md | 6 ++--- docs/platform/observability.md | 2 +- docs/platform/scope.md | 6 ++--- docs/quickstart.md | 6 ++--- 13 files changed, 58 insertions(+), 58 deletions(-) diff --git a/docs/api-reference/http/agents.md b/docs/api-reference/http/agents.md index 32be4ee..8a0779f 100644 --- a/docs/api-reference/http/agents.md +++ b/docs/api-reference/http/agents.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## PUT /agents/trust +## PUT /v1/agents/trust Set the trust level for an agent. @@ -41,7 +41,7 @@ Set the trust level for an agent. { "agent_id": "agent-gpt4", "trust_level": 0.85 } ``` -## GET /agents/trust +## GET /v1/agents/trust Get trust level for an agent. @@ -54,10 +54,10 @@ Get trust level for an agent. **Example:** ```bash -curl 'http://localhost:3050/agents/trust?agent_id=agent-gpt4&user_id=ethan' +curl 'http://localhost:3050/v1/agents/trust?agent_id=agent-gpt4&user_id=ethan' ``` -## GET /agents/conflicts +## GET /v1/agents/conflicts List open cross-agent memory conflicts. @@ -73,7 +73,7 @@ List open cross-agent memory conflicts. } ``` -## PUT /agents/conflicts/:id/resolve +## PUT /v1/agents/conflicts/:id/resolve Manually resolve a conflict. @@ -89,7 +89,7 @@ Manually resolve a conflict. { "id": "conflict-1", "status": "resolved_new" } ``` -## POST /agents/conflicts/auto-resolve +## POST /v1/agents/conflicts/auto-resolve Auto-resolve expired conflicts for a user. diff --git a/docs/api-reference/http/audit.md b/docs/api-reference/http/audit.md index 760c4b2..32bad9c 100644 --- a/docs/api-reference/http/audit.md +++ b/docs/api-reference/http/audit.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## GET /memories/audit/summary +## GET /v1/memories/audit/summary Mutation summary for a user (total creates, updates, deletes). @@ -23,10 +23,10 @@ Mutation summary for a user (total creates, updates, deletes). **Example:** ```bash -curl 'http://localhost:3050/memories/audit/summary?user_id=ethan' +curl 'http://localhost:3050/v1/memories/audit/summary?user_id=ethan' ``` -## GET /memories/audit/recent +## GET /v1/memories/audit/recent Recent mutations across all memories for a user. @@ -39,10 +39,10 @@ Recent mutations across all memories for a user. **Example:** ```bash -curl 'http://localhost:3050/memories/audit/recent?user_id=ethan&limit=5' +curl 'http://localhost:3050/v1/memories/audit/recent?user_id=ethan&limit=5' ``` -## GET /memories/:id/audit +## GET /v1/memories/:id/audit Full version history (audit trail) for a single memory. diff --git a/docs/api-reference/http/config.md b/docs/api-reference/http/config.md index 0666779..a11b090 100644 --- a/docs/api-reference/http/config.md +++ b/docs/api-reference/http/config.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## PUT /memories/config +## PUT /v1/memories/config Update runtime configuration at runtime. **Dev/test only** — production deploys return `410 Gone`. Gated by the startup-validated env var @@ -63,7 +63,7 @@ at first use, so mid-flight mutation never took effect in v1. - `410 Gone` (production — mutation disabled): ```json { - "error": "PUT /memories/config is deprecated for production", + "error": "PUT /v1/memories/config is deprecated for production", "detail": "Set CORE_RUNTIME_CONFIG_MUTATION_ENABLED=true to enable runtime mutation in dev/test environments. Production deploys should use startup env vars." } ``` diff --git a/docs/api-reference/http/consolidate-decay-cap.md b/docs/api-reference/http/consolidate-decay-cap.md index f1b2d37..bcdeaab 100644 --- a/docs/api-reference/http/consolidate-decay-cap.md +++ b/docs/api-reference/http/consolidate-decay-cap.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## POST /memories/consolidate +## POST /v1/memories/consolidate Identify or execute memory consolidation (merge near-duplicates). @@ -32,7 +32,7 @@ Identify or execute memory consolidation (merge near-duplicates). | `user_id` | string | required | | `execute` | boolean | `false` = dry-run (default), `true` = apply merges | -## POST /memories/decay +## POST /v1/memories/decay Evaluate memory decay and optionally archive stale memories. @@ -49,7 +49,7 @@ Evaluate memory decay and optionally archive stale memories. | `user_id` | string | required | | `dry_run` | boolean | `true` (default) = report only, `false` = archive candidates | -## POST /memories/reconcile +## POST /v1/memories/reconcile Reconcile deferred operations. Omit `user_id` to reconcile all users. @@ -58,13 +58,13 @@ Reconcile deferred operations. Omit `user_id` to reconcile all users. { "user_id": "ethan" } ``` -## GET /memories/reconcile/status +## GET /v1/memories/reconcile/status Check deferred reconciliation status. **Query params:** `user_id` (required) -## POST /memories/reset-source +## POST /v1/memories/reset-source Delete all memories from a specific source site for a user. diff --git a/docs/api-reference/http/conventions.md b/docs/api-reference/http/conventions.md index 23fd68d..42b9f01 100644 --- a/docs/api-reference/http/conventions.md +++ b/docs/api-reference/http/conventions.md @@ -9,7 +9,7 @@ Source of truth: atomicmemory-core/docs/api-reference.md (port). Update the core doc first, then sync here. */} -General conventions that apply across every `/memories/*` and `/agents/*` route. +General conventions that apply across every `/v1/memories/*` and `/v1/agents/*` route. ## Request and response format @@ -28,8 +28,8 @@ All endpoints return errors in a consistent format: | Status | Meaning | |--------|---------| | 400 | Invalid input (missing/malformed fields) | -| 404 | Resource not found (e.g. `GET /memories/:id` with an unknown id) | -| 410 | Gone — the route is deprecated in the current mode (e.g. `PUT /memories/config` in production) | +| 404 | Resource not found (e.g. `GET /v1/memories/:id` with an unknown id) | +| 410 | Gone — the route is deprecated in the current mode (e.g. `PUT /v1/memories/config` in production) | | 500 | Internal server error | ## CORS diff --git a/docs/api-reference/http/ingest.md b/docs/api-reference/http/ingest.md index ebe9fa4..16732b8 100644 --- a/docs/api-reference/http/ingest.md +++ b/docs/api-reference/http/ingest.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## POST /memories/ingest +## POST /v1/memories/ingest Full ingest pipeline: LLM fact extraction, embedding, dedup, entity graph, link discovery. @@ -55,7 +55,7 @@ Full ingest pipeline: LLM fact extraction, embedding, dedup, entity graph, link **Example:** ```bash -curl -X POST http://localhost:3050/memories/ingest \ +curl -X POST http://localhost:3050/v1/memories/ingest \ -H 'Content-Type: application/json' \ -d '{ "user_id": "docs-demo", @@ -65,11 +65,11 @@ curl -X POST http://localhost:3050/memories/ingest \ }' ``` -## POST /memories/ingest/quick +## POST /v1/memories/ingest/quick Fast-path ingest optimized for low latency. Uses lightweight extraction without the full LLM pipeline. -**Request:** Same as `/memories/ingest`. +**Request:** Same as `/v1/memories/ingest`. **Response** (captured from running prototype): ```json @@ -105,7 +105,7 @@ When the fact is a duplicate, the response shows zero extractions: **Example:** ```bash -curl -X POST http://localhost:3050/memories/ingest/quick \ +curl -X POST http://localhost:3050/v1/memories/ingest/quick \ -H 'Content-Type: application/json' \ -d '{ "user_id": "docs-demo", diff --git a/docs/api-reference/http/lessons.md b/docs/api-reference/http/lessons.md index c23a85f..0d1ef40 100644 --- a/docs/api-reference/http/lessons.md +++ b/docs/api-reference/http/lessons.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## GET /memories/lessons +## GET /v1/memories/lessons List active lessons for a user. @@ -31,13 +31,13 @@ List active lessons for a user. } ``` -## GET /memories/lessons/stats +## GET /v1/memories/lessons/stats Lesson statistics for a user. **Query params:** `user_id` (required) -## POST /memories/lessons/report +## POST /v1/memories/lessons/report Report a new lesson/pattern. @@ -56,7 +56,7 @@ Report a new lesson/pattern. { "lessonId": "lesson-abc123" } ``` -## DELETE /memories/lessons/:id +## DELETE /v1/memories/lessons/:id Deactivate a lesson. diff --git a/docs/api-reference/http/list-get-delete.md b/docs/api-reference/http/list-get-delete.md index 31a7271..8a86620 100644 --- a/docs/api-reference/http/list-get-delete.md +++ b/docs/api-reference/http/list-get-delete.md @@ -26,7 +26,7 @@ Top-level server liveness check. { "status": "ok" } ``` -### GET /memories/health +### GET /v1/memories/health Memory subsystem health with active runtime config. @@ -48,7 +48,7 @@ Memory subsystem health with active runtime config. ## CRUD -### GET /memories/list +### GET /v1/memories/list List memories for a user with pagination. @@ -95,10 +95,10 @@ Scope resolution: when `workspace_id` is absent, the list uses the user scope an **Example:** ```bash -curl 'http://localhost:3050/memories/list?user_id=docs-demo&limit=3&offset=0' +curl 'http://localhost:3050/v1/memories/list?user_id=docs-demo&limit=3&offset=0' ``` -### GET /memories/:id +### GET /v1/memories/:id Get a single memory by ID. Returns the full memory object including embedding, keywords, network, and audit fields. @@ -151,10 +151,10 @@ Returns `404 { "error": "Memory not found" }` if the ID does not exist for the g **Example:** ```bash -curl 'http://localhost:3050/memories/3fa330cb-ee9e-4614-825c-1ce27539d24d?user_id=docs-demo' +curl 'http://localhost:3050/v1/memories/3fa330cb-ee9e-4614-825c-1ce27539d24d?user_id=docs-demo' ``` -### DELETE /memories/:id +### DELETE /v1/memories/:id Delete a single memory. @@ -175,10 +175,10 @@ Returns `404 { "error": "Memory not found" }` when the memory does not exist in **Example:** ```bash -curl -X DELETE 'http://localhost:3050/memories/3fa330cb-ee9e-4614-825c-1ce27539d24d?user_id=docs-demo' +curl -X DELETE 'http://localhost:3050/v1/memories/3fa330cb-ee9e-4614-825c-1ce27539d24d?user_id=docs-demo' ``` -### POST /memories/expand +### POST /v1/memories/expand Expand a set of memory IDs into their full content. Used for follow-up retrieval after search returns `expand_ids`. @@ -201,7 +201,7 @@ Expand a set of memory IDs into their full content. Used for follow-up retrieval ## Stats & Cap -### GET /memories/stats +### GET /v1/memories/stats Per-user memory statistics. @@ -221,10 +221,10 @@ Per-user memory statistics. **Example:** ```bash -curl 'http://localhost:3050/memories/stats?user_id=docs-demo' +curl 'http://localhost:3050/v1/memories/stats?user_id=docs-demo' ``` -### GET /memories/cap +### GET /v1/memories/cap Check user storage quota. @@ -232,5 +232,5 @@ Check user storage quota. **Example:** ```bash -curl 'http://localhost:3050/memories/cap?user_id=ethan' +curl 'http://localhost:3050/v1/memories/cap?user_id=ethan' ``` diff --git a/docs/api-reference/http/search.md b/docs/api-reference/http/search.md index 8d09fa8..2aaa5b8 100644 --- a/docs/api-reference/http/search.md +++ b/docs/api-reference/http/search.md @@ -15,7 +15,7 @@ Base URL: `http://localhost:3050` All request bodies are JSON (`Content-Type: application/json`). Field names on the raw HTTP prototype surface use **snake_case**. -## POST /memories/search +## POST /v1/memories/search Full search with query expansion, co-retrieval, reranking, and LLM repair loop. @@ -105,19 +105,19 @@ Scope resolution follows the platform's [scope contract](/platform/scope): when | `injection_text` | Pre-formatted markdown grouped by `### Subject: site/` with date-stamped `[context]`/`[answer]` bullets | | `citations` | Memory IDs referenced in `injection_text`, matching `memories[].id` order | | `tier_assignments` | Present when `retrieval_mode` is `tiered` | -| `expand_ids` | IDs for follow-up `/memories/expand` calls | +| `expand_ids` | IDs for follow-up `/v1/memories/expand` calls | | `lesson_check` | Safety check against learned lessons | | `consensus` | Conflict resolution stats when multiple memories conflict | | `observability` | Optional trace payload (`retrieval` / `packaging` / `assembly` sub-objects) — present when the runtime produced per-stage summaries. See [observability](/platform/observability) for the schema. | **Example:** ```bash -curl -X POST http://localhost:3050/memories/search \ +curl -X POST http://localhost:3050/v1/memories/search \ -H 'Content-Type: application/json' \ -d '{"user_id": "docs-demo", "query": "Do they have any food allergies?", "limit": 3}' ``` -## POST /memories/search/fast +## POST /v1/memories/search/fast Latency-optimized search (sub-200ms target). Skips the LLM repair loop and cross-encoder reranking. @@ -134,7 +134,7 @@ Latency-optimized search (sub-200ms target). Skips the LLM repair loop and cross | `agent_id` | string | no | Scope search to an agent within the workspace | | `agent_scope` | string | no | Agent visibility scope: `all`, `self`, or `others` | -**Response** (captured from running prototype — same schema as `/memories/search`, including `scope` and optional `observability`): +**Response** (captured from running prototype — same schema as `/v1/memories/search`, including `scope` and optional `observability`): ```json { "count": 3, @@ -181,7 +181,7 @@ Note: `/search/fast` composite `score` values are higher than `/search` because **Example:** ```bash -curl -X POST http://localhost:3050/memories/search/fast \ +curl -X POST http://localhost:3050/v1/memories/search/fast \ -H 'Content-Type: application/json' \ -d '{"user_id": "docs-demo", "query": "What is their tech stack?", "limit": 3}' ``` diff --git a/docs/platform/composition.md b/docs/platform/composition.md index 2701e1a..3e9bf65 100644 --- a/docs/platform/composition.md +++ b/docs/platform/composition.md @@ -121,8 +121,8 @@ export function createApp(runtime: CoreRuntime): ReturnType { app.use(express.json({ limit: '1mb' })); - app.use('/memories', createMemoryRouter(runtime.services.memory, runtime.configRouteAdapter)); - app.use('/agents', createAgentRouter(runtime.repos.trust)); + app.use('/v1/memories', createMemoryRouter(runtime.services.memory, runtime.configRouteAdapter)); + app.use('/v1/agents', createAgentRouter(runtime.repos.trust)); app.get('/health', (_req, res) => { res.json({ status: 'ok' }); @@ -196,7 +196,7 @@ describe('Phase 6 research-consumption seams', () => { const write = await runtime.services.memory.ingest(TEST_USER, CONVERSATION, 'test-site'); const writtenIds = new Set(write.memoryIds); - const searchRes = await fetch(`${server.baseUrl}/memories/search`, { + const searchRes = await fetch(`${server.baseUrl}/v1/memories/search`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ user_id: TEST_USER, query: 'What stack does the user use?' }), diff --git a/docs/platform/observability.md b/docs/platform/observability.md index f9a41cf..e0de963 100644 --- a/docs/platform/observability.md +++ b/docs/platform/observability.md @@ -276,7 +276,7 @@ function buildRetrievalObservability(result: RetrievalResult): RetrievalObservab } ``` -So a `POST /memories/search` response looks like this (abridged): +So a `POST /v1/memories/search` response looks like this (abridged): ```json { diff --git a/docs/platform/scope.md b/docs/platform/scope.md index a11d026..8e03602 100644 --- a/docs/platform/scope.md +++ b/docs/platform/scope.md @@ -151,7 +151,7 @@ function registerListRoute(router: Router, service: MemoryService): void { : await service.list(userId, limit, offset, sourceSite, episodeId); res.json({ memories, count: memories.length }); } catch (err) { - handleRouteError(res, 'GET /memories/list', err); + handleRouteError(res, 'GET /v1/memories/list', err); } }); } @@ -160,7 +160,7 @@ function registerListRoute(router: Router, service: MemoryService): void { Concretely, this request fails: ```http -GET /memories/list?user_id=u-123&workspace_id=ws-abc +GET /v1/memories/list?user_id=u-123&workspace_id=ws-abc HTTP/1.1 400 Bad Request { "error": "agent_id is required for workspace queries" } ``` @@ -168,7 +168,7 @@ HTTP/1.1 400 Bad Request And this one succeeds: ```http -GET /memories/list?user_id=u-123&workspace_id=ws-abc&agent_id=a-planner +GET /v1/memories/list?user_id=u-123&workspace_id=ws-abc&agent_id=a-planner HTTP/1.1 200 OK { "memories": [...], "count": 7 } ``` diff --git a/docs/quickstart.md b/docs/quickstart.md index ecf63ca..d909ab6 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -34,7 +34,7 @@ The `-d` runs detached; `--build` compiles the image on first run. Migrations ex Hit the memory subsystem health endpoint to confirm the server is live and see the active runtime config. ```bash -curl http://localhost:3050/memories/health +curl http://localhost:3050/v1/memories/health ``` You should get back a JSON object with `"status": "ok"` and a `config` snapshot showing the selected embedding and LLM providers. @@ -44,7 +44,7 @@ You should get back a JSON object with `"status": "ok"` and a `config` snapshot Send a conversation and let AtomicMemory extract structured facts, embed them, and run AUDN to decide what to store. ```bash -curl -X POST http://localhost:3050/memories/ingest \ +curl -X POST http://localhost:3050/v1/memories/ingest \ -H 'Content-Type: application/json' \ -d '{"user_id":"alice","conversation":"user: I ship Go backends and TypeScript frontends.","source_site":"quickstart"}' ``` @@ -56,7 +56,7 @@ The response reports `factsExtracted`, `memoriesStored`, and the `memoryIds` of Query the memories you just created. AtomicMemory runs a hybrid retrieval (vector + BM25/FTS with RRF fusion), reranks, and packages the result. ```bash -curl -X POST http://localhost:3050/memories/search \ +curl -X POST http://localhost:3050/v1/memories/search \ -H 'Content-Type: application/json' \ -d '{"user_id":"alice","query":"what stack does alice use?"}' ```