Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/cn/open_source/modules/api_deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,26 @@

- **`server_api_ext.py`** 和 **`Dockerfile.krolik`** 是某位开发者扩展后的 API 及部署配置,**仅供参考**。这些内容尚未与云服务集成,仍处于测试阶段。
- 如需扩展或自定义行为,可参考上述文件,按需使用或改造。

## 项目记忆接口联调

未配置项目数据库连接 `MEMOS_PROJECT_MEMORY_DSN` 时,MemOS 启动后默认提供联调空间 `mock-space`。不同测试者可以用自己的 `user_id` 检索同一组内置样例,无需建空间、准备数据或设置环境变量。部署后,把下面的地址换成联调服务的 IP 和端口即可。

```bash
MEMOS_URL=http://127.0.0.1:9801
curl -sS "$MEMOS_URL/product/search" \
-H 'Content-Type: application/json' \
-d '{"user_id":"tester","space_ids":["mock-space"],"include_memory_view":["project"],"project_result_format":"item","project_item_types":["decision"],"query":"项目采用什么数据库?"}'

curl -sS "$MEMOS_URL/product/get_memory/mock-decision"
```

第一条响应的 `data.project_item_list` 里应有 `mock-decision`,第二条能用这个 ID 读到相同的决策内容。任意非空查询都使用同一组样例,适合核对请求参数和返回字段。其他读接口也可以直接测试。

| 接口 | 请求示例 |
| --- | --- |
| `POST /product/get_memory` | `{"space_id":"mock-space","page":1,"page_size":10}` |
| `GET /product/get_memory/mock-experience` | 按 ID 读经验 |
| `POST /product/get_message` | `{"conversation_id":"mock-session","space_id":"mock-space"}` |

接入项目数据库后,设置 `MEMOS_PROJECT_MEMORY_DSN` 并重启,默认使用真实数据。需要临时切回样例时可设置 `MEMOS_PROJECT_MEMORY_MOCK=1`。设置为 `0` 可关闭样例,此时项目检索需要数据库连接。
80 changes: 47 additions & 33 deletions src/memos/api/handlers/project_retrieval.py
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
"""Project read adapter for the existing product endpoints."""

import asyncio
import hmac
import os

from collections.abc import Callable, Iterator
from concurrent.futures import Future
from contextlib import contextmanager
from contextlib import contextmanager, nullcontext
from contextvars import ContextVar
from dataclasses import dataclass
from functools import partial
Expand Down Expand Up @@ -85,34 +84,44 @@ def _scope(request: Request, spaces: list[str] | None, domains: list[str]) -> Sc
if not set(spaces) <= access.readable_space_ids:
raise ProjectReadError(404, "SPACE_NOT_FOUND", "Space not found")
return Scope(access.tenant_id, tuple(spaces), tuple(domains))
# Service-to-service deployment: the gateway checks membership and supplies space IDs.
token = os.getenv("MEMOS_PROJECT_MEMORY_GATEWAY_KEY")
tenant = os.getenv("MEMOS_PROJECT_MEMORY_TENANT_ID")
auth = request.headers.get("Authorization", "").split(" ", 1)
if tenant and not token and os.getenv("MEMOS_PROJECT_MEMORY_INTERNAL") == "1":
return Scope(tenant, None if spaces is None else tuple(spaces), tuple(domains))
if not (
token
and tenant
and len(auth) == 2
and auth[0] == "Token"
and hmac.compare_digest(auth[1].encode(), token.encode())
):
raise HTTPException(401, "Project memory authentication required")
# The engineering gateway authenticates the caller before forwarding /product requests.
tenant = os.getenv("MEMOS_PROJECT_MEMORY_TENANT_ID") or None
return Scope(tenant, None if spaces is None else tuple(spaces), tuple(domains))


@contextmanager
def project_retrieval_lifespan(app: FastAPI, components: dict) -> Iterator[None]:
if getattr(app.state, "project_retrieval", None) is not None:
yield
return
dsn = os.getenv("MEMOS_PROJECT_MEMORY_DSN")
if not dsn or getattr(app.state, "project_retrieval", None) is not None:
mock_setting = os.getenv("MEMOS_PROJECT_MEMORY_MOCK")
if mock_setting == "1" or (not mock_setting and not dsn):
from memos.project_memory.mock_store import MockProjectStore

store = MockProjectStore(os.getenv("MEMOS_PROJECT_MEMORY_TENANT_ID") or "mock-tenant")
backend = nullcontext(ProjectRetrieval(store, message_store=store))
logger.info("Project memory mock enabled; serving the built-in mock-space fixture")
elif dsn:
backend = _postgres_retrieval(dsn, components)
else:
yield
return
with backend as service:
app.state.project_retrieval = service
try:
yield
finally:
del app.state.project_retrieval
service.close()


@contextmanager
def _postgres_retrieval(dsn: str, components: dict) -> Iterator[ProjectRetrieval]:
try:
from psycopg2.pool import ThreadedConnectionPool
except ImportError as exc:
raise ImportError("Project retrieval requires psycopg2-binary") from exc
pool = ThreadedConnectionPool(1, 16, dsn, connect_timeout=3)
embedder = components.get("embedder")
model = getattr(getattr(embedder, "config", None), "model_name_or_path", None)

Expand All @@ -127,14 +136,12 @@ def project_retrieval_lifespan(app: FastAPI, components: dict) -> Iterator[None]
def embed(text: str) -> Vector:
return Vector(model=model, values=embedder.embed([text])[0])

pool = ThreadedConnectionPool(1, 16, dsn, connect_timeout=3)
try:
app.state.project_retrieval = ProjectRetrieval(
yield ProjectRetrieval(
RetrievalStore(pool), embed if model else None, components.get("project_message_store")
)
yield
finally:
app.state.project_retrieval.close()
del app.state.project_retrieval
pool.closeall()


Expand Down Expand Up @@ -245,12 +252,7 @@ async def search_project(
async def get_project(
request: Request, memory_id: str, space_id: str | None, view: str | None
) -> dict | None:
try:
scope = _scope(request, _names(space_id, "space_ids") if space_id is not None else None, [])
except HTTPException as exc:
if exc.status_code == 401 and space_id is None and view is None:
return None
raise
scope = _scope(request, _names(space_id, "space_ids") if space_id is not None else None, [])
service = _service(request)
try:
data = await asyncio.wait_for(
Expand Down Expand Up @@ -302,12 +304,24 @@ async def project_messages(request: Request, req: ProjectMessagesRequest) -> dic
request, _names(req.space_id, "space_ids") if req.space_id is not None else None, []
)
service = _service(request)
spaces = await asyncio.to_thread(service.store.visible_spaces, scope)
if req.space_id is not None and not spaces:
by_tenant = await asyncio.to_thread(service.store.spaces_by_tenant, scope)
if req.space_id is not None and not by_tenant:
raise ProjectReadError(404, "SPACE_NOT_FOUND", "Space not found")
if service.message_store is None:
raise HTTPException(500, "Project message store is not configured")
msgs = await asyncio.to_thread(
read_messages, service.message_store, spaces, req.conversation_id, req.message_limit_number
)
msgs = []
for spaces in by_tenant.values():
batch = await asyncio.to_thread(
read_messages,
service.message_store,
spaces,
req.conversation_id,
req.message_limit_number,
)
if batch:
if msgs:
raise HTTPException(
409, "Conversation ID exists in multiple tenants; supply space_id"
)
msgs = batch
return {"code": 200, "message": "ok", "data": {"message_detail_list": msgs}}
152 changes: 152 additions & 0 deletions src/memos/project_memory/mock_store.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
"""Fixed project data for HTTP integration tests before the project database is available."""

import operator

from memos.project_memory.index import Vector
from memos.project_memory.store import Hit, MissingSpaceError, Scope, UnknownDomainError
from memos.project_memory.views import component, parse_topic_filters, timestamp, topic_detail


SPACE = "mock-space"
SESSION = "mock-session"
TIME = "2026-01-15T10:00:00+08:00"
HEADER = {
"id": "mock-topic",
"domain": "代码开发",
"topic_name": "项目记忆存储方案",
"topic_summary": "项目记忆使用 PostgreSQL 存储,按空间检索。",
"topic_description": "供接口联调使用的示例主题,包含数据库选型决策和联调经验。",
"create_time": TIME,
"update_time": TIME,
"sources": [{"conversation_id": SESSION, "user_id": ["mock-user"], "agent_id": ["memmy"]}],
}
MESSAGE = {
"message_id": "mock-message",
"role": "user",
"chat_time": TIME,
"content": "这个项目的记忆统一存到 PostgreSQL,按项目空间查询。",
"role_id": "mock-user",
}
TURN = {
"id": "mock-turn",
"turn_id": "mock-turn",
"conversation_id": SESSION,
"source_task_id": "mock-task",
"message_ids": [MESSAGE["message_id"]],
"topic_ids": [HEADER["id"]],
"user_id": "mock-user",
"agent_id": "memmy",
"chat_time": TIME,
"content": MESSAGE["content"],
"cache_policy": "immutable",
}

ENTRIES = [
(kind, {"id": f"mock-{kind}", "content": content, "time": TIME, "user_ids": ["mock-user"]})
for kind, content in (
("decision", "项目记忆使用 PostgreSQL 存储。"),
("experience", "联调时先用检索返回的 ID 回查详情,确认读到的是同一条记忆。"),
("timeline", "项目记忆检索接口开始联调。"),
)
]


class MockProjectStore:
def __init__(self, tenant: str):
self.tenant = tenant

def spaces_by_tenant(self, scope: Scope) -> dict[str, list[str]]:
if scope.tenant not in (None, self.tenant) or (
scope.spaces is not None and SPACE not in scope.spaces
):
return {}
return {self.tenant: [SPACE]}

def validate(self, scope: Scope) -> Scope:
if set(scope.spaces or ()) != {SPACE} or not self.spaces_by_tenant(scope):
raise MissingSpaceError
if set(scope.domains) - {HEADER["domain"]}:
raise UnknownDomainError
return Scope(self.tenant, (SPACE,), scope.domains)

def recall(
self,
scope: Scope,
channel: str,
query: str,
vector: Vector | None,
session: str | None,
limit: int,
item_types: tuple[str, ...],
result_format: str,
threshold: float,
) -> tuple[list[Hit], bool]:
# A fixed match lets clients test response handling with any query text.
if threshold > 1:
return [], False
if channel == "trajectory":
rows = [("trajectory_detail_list", "trajectory", {**TURN, "space_id": SPACE})]
elif result_format == "item":
rows = [
("project_item_list", kind, component(kind, row, HEADER, SPACE, False))
for kind, row in [("topic", HEADER), *ENTRIES]
if kind in item_types
]
else:
entries = [(kind, row) for kind, row in ENTRIES if kind in item_types]
rows = [("topic_detail_list", "topic", topic_detail(HEADER, SPACE, entries, False))]
return [
Hit(group, {**row, "relativity": 1.0}, 1.0, session == SESSION, kind)
for group, kind, row in rows
], False

def get(self, scope: Scope, memory_id: str, metadata_only: bool) -> dict | None:
if not self.spaces_by_tenant(scope):
return None
for kind, row in [("topic", HEADER), *ENTRIES, ("trajectory", TURN)]:
if memory_id != row["id"]:
continue
meta = {
"id": memory_id,
"space_id": SPACE,
"kind": kind,
"cache_policy": row.get("cache_policy", "live"),
}
if kind != "trajectory":
meta["topic_id"] = HEADER["id"]
if metadata_only:
return meta
if kind == "topic":
return {**topic_detail(HEADER, SPACE, ENTRIES, True), **meta}
if kind == "trajectory":
return {**TURN, **meta}
return {**component(kind, row, HEADER, SPACE, True), **meta}
return None

def list_topics(self, scope: Scope, page: int, size: int | None, filters: dict) -> dict:
self.validate(scope)
related, bounds = parse_topic_filters(filters)
operators = {
"gte": operator.ge,
"gt": operator.gt,
"lte": operator.le,
"lt": operator.lt,
"eq": operator.eq,
}
source = HEADER["sources"][0]
matches = related is None or related in source["user_id"] or related in source["agent_id"]
matches = matches and all(
operators[op](timestamp(HEADER[field]), value) for field, op, value in bounds
)
rows = (
[topic_detail(HEADER, SPACE, ENTRIES, True)]
if matches and (size is None or page == 1)
else []
)
return {"space_id": SPACE, "total": int(matches), "topic_detail_list": rows}

def list_messages(self, space_id: str, conversation_id: str) -> list[dict]:
return [dict(MESSAGE)] if (space_id, conversation_id) == (SPACE, SESSION) else []

def log_recall(self, scope: Scope, session: str, topics: list[dict]) -> None:
"""The read-only fixture does not persist recall logs."""
12 changes: 9 additions & 3 deletions src/memos/project_memory/retrieval.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,20 @@
from contextvars import copy_context
from functools import partial
from threading import BoundedSemaphore
from typing import TYPE_CHECKING

from memos.log import get_logger
from memos.project_memory.index import Vector, terms
from memos.project_memory.messages import MessageStore
from memos.project_memory.store import Hit, RetrievalStore, Scope
from memos.project_memory.store import Hit, Scope
from memos.project_memory.views import ITEM_TYPES


if TYPE_CHECKING:
from memos.project_memory.mock_store import MockProjectStore
from memos.project_memory.store import RetrievalStore


logger = get_logger(__name__)
PROJECT_GROUPS = {"project": "topic_detail_list", "trajectory": "trajectory_detail_list"}
PERSONAL_GROUPS = {
Expand Down Expand Up @@ -74,7 +80,7 @@ def priority(key: tuple) -> tuple:
class ProjectRetrieval:
def __init__(
self,
store: RetrievalStore,
store: "RetrievalStore | MockProjectStore",
embed: Callable[[str], Vector] | None = None,
message_store: MessageStore | None = None,
):
Expand Down Expand Up @@ -115,7 +121,7 @@ async def search(
) -> dict:
deadline = asyncio.get_running_loop().time() + 0.46
# Scope errors fail the entire request, including mixed searches.
await asyncio.wait_for(asyncio.to_thread(self.store.validate, scope), 0.25)
scope = await asyncio.wait_for(asyncio.to_thread(self.store.validate, scope), 0.25)
degraded = set()
lanes = {}
project_ready = Future()
Expand Down
Loading
Loading