memoraos 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- memoraos/__init__.py +8 -0
- memoraos/api/__init__.py +9 -0
- memoraos/api/app.py +325 -0
- memoraos/api/auth.py +88 -0
- memoraos/cli.py +206 -0
- memoraos/client.py +66 -0
- memoraos/config.py +184 -0
- memoraos/consolidation/__init__.py +3 -0
- memoraos/consolidation/engine.py +369 -0
- memoraos/contracts.py +247 -0
- memoraos/engine.py +836 -0
- memoraos/evaluation/__init__.py +4 -0
- memoraos/evaluation/metrics.py +54 -0
- memoraos/evaluation/runner.py +58 -0
- memoraos/extraction/__init__.py +23 -0
- memoraos/extraction/base.py +43 -0
- memoraos/extraction/llm.py +187 -0
- memoraos/extraction/pipeline.py +93 -0
- memoraos/extraction/rules.py +27 -0
- memoraos/extraction/schema.py +36 -0
- memoraos/extraction/validate.py +112 -0
- memoraos/extraction/values.py +133 -0
- memoraos/fusion/__init__.py +27 -0
- memoraos/fusion/paths.py +238 -0
- memoraos/fusion/plan.py +118 -0
- memoraos/ingestion/__init__.py +15 -0
- memoraos/ingestion/classify.py +75 -0
- memoraos/ingestion/dates.py +170 -0
- memoraos/ingestion/extract.py +315 -0
- memoraos/ingestion/lexicon.py +90 -0
- memoraos/latent/__init__.py +20 -0
- memoraos/latent/base.py +73 -0
- memoraos/latent/index.py +76 -0
- memoraos/latent/slots.py +91 -0
- memoraos/mcp/__init__.py +3 -0
- memoraos/mcp/server.py +131 -0
- memoraos/models.py +187 -0
- memoraos/providers/__init__.py +49 -0
- memoraos/providers/base.py +70 -0
- memoraos/providers/embeddings.py +162 -0
- memoraos/providers/http.py +248 -0
- memoraos/providers/local.py +79 -0
- memoraos/providers/rerank.py +87 -0
- memoraos/recall.py +927 -0
- memoraos/retrieval/__init__.py +5 -0
- memoraos/retrieval/ann.py +59 -0
- memoraos/retrieval/answer_type.py +38 -0
- memoraos/retrieval/entity.py +115 -0
- memoraos/retrieval/expand.py +117 -0
- memoraos/retrieval/facts.py +211 -0
- memoraos/retrieval/fusion.py +59 -0
- memoraos/retrieval/graph.py +153 -0
- memoraos/retrieval/lexical.py +79 -0
- memoraos/retrieval/vector.py +93 -0
- memoraos/routing/__init__.py +14 -0
- memoraos/routing/learning.py +77 -0
- memoraos/routing/router.py +254 -0
- memoraos/security.py +87 -0
- memoraos/storage/__init__.py +4 -0
- memoraos/storage/crypto.py +79 -0
- memoraos/storage/db.py +401 -0
- memoraos/storage/visibility.py +41 -0
- memoraos/store.py +333 -0
- memoraos/truth/__init__.py +3 -0
- memoraos/truth/answer.py +252 -0
- memoraos/truth/timeline.py +225 -0
- memoraos/util.py +105 -0
- memoraos-0.2.0.dist-info/METADATA +405 -0
- memoraos-0.2.0.dist-info/RECORD +73 -0
- memoraos-0.2.0.dist-info/WHEEL +5 -0
- memoraos-0.2.0.dist-info/entry_points.txt +2 -0
- memoraos-0.2.0.dist-info/licenses/LICENSE +202 -0
- memoraos-0.2.0.dist-info/top_level.txt +1 -0
memoraos/__init__.py
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""MemoraOS: local-first adaptive memory for AI agents."""
|
|
2
|
+
|
|
3
|
+
from .config import Settings
|
|
4
|
+
from .engine import MemoryOS, NotFoundError, PermissionDenied
|
|
5
|
+
from .models import RecallResult, Scope
|
|
6
|
+
|
|
7
|
+
__version__ = "0.2.0"
|
|
8
|
+
__all__ = ["MemoryOS", "NotFoundError", "PermissionDenied", "RecallResult", "Scope", "Settings", "__version__"]
|
memoraos/api/__init__.py
ADDED
memoraos/api/app.py
ADDED
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
"""FastAPI REST application. Secure by default: refuses to start without API keys."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any, Literal
|
|
8
|
+
|
|
9
|
+
from fastapi import Depends, FastAPI, Header, HTTPException, Query, Request
|
|
10
|
+
from fastapi.middleware.cors import CORSMiddleware
|
|
11
|
+
from fastapi.responses import JSONResponse
|
|
12
|
+
from pydantic import BaseModel, Field
|
|
13
|
+
|
|
14
|
+
from .. import __version__
|
|
15
|
+
from ..engine import MemoryOS, NotFoundError, PermissionDenied
|
|
16
|
+
from .auth import ApiKeyStore, Principal
|
|
17
|
+
|
|
18
|
+
UserId = Field(min_length=1, max_length=200)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class ScopeBody(BaseModel):
|
|
22
|
+
user_id: str = UserId
|
|
23
|
+
agent_id: str | None = Field(default=None, max_length=200)
|
|
24
|
+
session_id: str | None = Field(default=None, max_length=200)
|
|
25
|
+
project_id: str | None = Field(default=None, max_length=200)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class RememberBody(ScopeBody):
|
|
29
|
+
text: str = Field(min_length=1, max_length=2_000_000)
|
|
30
|
+
level: Literal["user", "agent", "session", "project", "org"] = "user"
|
|
31
|
+
source_type: Literal["user_statement", "conversation", "document", "structured", "external", "inferred"] = "user_statement"
|
|
32
|
+
origin: str | None = Field(default=None, max_length=500)
|
|
33
|
+
category: Literal["episodic", "semantic", "procedural"] | None = None
|
|
34
|
+
effective_at: str | None = None
|
|
35
|
+
reliability: float | None = Field(default=None, ge=0, le=1)
|
|
36
|
+
verification: Literal["unverified", "verified", "disputed"] = "unverified"
|
|
37
|
+
metadata: dict[str, Any] | None = None
|
|
38
|
+
facts: list[dict[str, Any]] | None = Field(default=None, max_length=500)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class ConversationBody(ScopeBody):
|
|
42
|
+
messages: list[dict[str, Any]] = Field(min_length=1, max_length=1000)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class JsonBody(ScopeBody):
|
|
46
|
+
record: dict[str, Any] | list[dict[str, Any]]
|
|
47
|
+
subject: str | None = None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class RecallBody(ScopeBody):
|
|
51
|
+
query: str = Field(min_length=1, max_length=2000)
|
|
52
|
+
top_k: int | None = Field(default=None, ge=1, le=100)
|
|
53
|
+
as_of: str | None = None
|
|
54
|
+
strategy: Literal["exact", "bm25", "vector", "hybrid", "graph", "fusion", "temporal", "episodic", "procedural", "latent", "multistage"] | None = None
|
|
55
|
+
synthesize: bool = False
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class CorrectBody(BaseModel):
|
|
59
|
+
user_id: str = UserId
|
|
60
|
+
new_content: str = Field(min_length=1, max_length=2_000_000)
|
|
61
|
+
reason: str | None = Field(default=None, max_length=500)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class VerifyBody(BaseModel):
|
|
65
|
+
user_id: str = UserId
|
|
66
|
+
status: Literal["unverified", "verified", "disputed"]
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class FeedbackBody(BaseModel):
|
|
70
|
+
recall_id: str
|
|
71
|
+
correct: bool | None = None
|
|
72
|
+
relevance: float | None = Field(default=None, ge=0, le=1)
|
|
73
|
+
comment: str | None = Field(default=None, max_length=1000)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class ConsolidateBody(ScopeBody):
|
|
77
|
+
mode: Literal["manual", "incremental", "dry_run"] = "manual"
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def create_app(
|
|
81
|
+
engine: MemoryOS,
|
|
82
|
+
keys: ApiKeyStore | None = None,
|
|
83
|
+
*,
|
|
84
|
+
insecure_no_auth: bool = False,
|
|
85
|
+
reports_dir: Path | None = None,
|
|
86
|
+
cors_origins: list[str] | None = None,
|
|
87
|
+
) -> FastAPI:
|
|
88
|
+
if keys is None or len(keys) == 0:
|
|
89
|
+
if not insecure_no_auth:
|
|
90
|
+
raise RuntimeError(
|
|
91
|
+
"No API keys configured. Create one with `memoraos keys create --tenant <t>` or pass insecure_no_auth=True for local development only."
|
|
92
|
+
)
|
|
93
|
+
app = FastAPI(title="MemoraOS API", version=__version__, docs_url="/docs", redoc_url=None)
|
|
94
|
+
if cors_origins:
|
|
95
|
+
app.add_middleware(CORSMiddleware, allow_origins=cors_origins, allow_methods=["*"], allow_headers=["Authorization", "Content-Type"])
|
|
96
|
+
reports = reports_dir or Path("benchmarks/reports")
|
|
97
|
+
|
|
98
|
+
def auth(request: Request, authorization: str | None = Header(default=None)) -> Principal:
|
|
99
|
+
if insecure_no_auth and (keys is None or len(keys) == 0):
|
|
100
|
+
return Principal("default", "admin", ("*",), "insecure")
|
|
101
|
+
token = authorization.split(" ", 1)[1].strip() if authorization and authorization.lower().startswith("bearer ") else None
|
|
102
|
+
p = keys.authenticate(token) if keys else None
|
|
103
|
+
if not p:
|
|
104
|
+
raise HTTPException(401, "invalid or missing API key", headers={"WWW-Authenticate": "Bearer"})
|
|
105
|
+
return p
|
|
106
|
+
|
|
107
|
+
def need(role: str):
|
|
108
|
+
def dep(p: Principal = Depends(auth)) -> Principal:
|
|
109
|
+
if not p.can(role):
|
|
110
|
+
raise HTTPException(403, f"this key has role '{p.role}'; '{role}' required")
|
|
111
|
+
return p
|
|
112
|
+
|
|
113
|
+
return dep
|
|
114
|
+
|
|
115
|
+
def act_as(p: Principal, user_id: str) -> None:
|
|
116
|
+
if not p.may_act_as(user_id):
|
|
117
|
+
raise HTTPException(403, "this key may not act as that user")
|
|
118
|
+
|
|
119
|
+
def audit(p: Principal, action: str, target: str | None = None) -> None:
|
|
120
|
+
engine.store.audit(p.tenant_id, p.fingerprint, action, target)
|
|
121
|
+
|
|
122
|
+
@app.exception_handler(NotFoundError)
|
|
123
|
+
async def _nf(_: Request, exc: NotFoundError) -> JSONResponse:
|
|
124
|
+
return JSONResponse({"detail": "not found"}, status_code=404)
|
|
125
|
+
|
|
126
|
+
@app.exception_handler(PermissionDenied)
|
|
127
|
+
async def _pd(_: Request, exc: PermissionDenied) -> JSONResponse:
|
|
128
|
+
return JSONResponse({"detail": str(exc)}, status_code=403)
|
|
129
|
+
|
|
130
|
+
@app.exception_handler(ValueError)
|
|
131
|
+
async def _ve(_: Request, exc: ValueError) -> JSONResponse:
|
|
132
|
+
return JSONResponse({"detail": str(exc)}, status_code=422)
|
|
133
|
+
|
|
134
|
+
def scope_kw(b: ScopeBody) -> dict:
|
|
135
|
+
return {"agent_id": b.agent_id, "session_id": b.session_id, "project_id": b.project_id}
|
|
136
|
+
|
|
137
|
+
# ---- meta ---------------------------------------------------------------------------
|
|
138
|
+
@app.get("/v1/health")
|
|
139
|
+
def health() -> dict:
|
|
140
|
+
return {"status": "ok", "version": __version__}
|
|
141
|
+
|
|
142
|
+
@app.get("/v1/system/health")
|
|
143
|
+
def system_health(p: Principal = Depends(need("read"))) -> dict:
|
|
144
|
+
return engine.health()
|
|
145
|
+
|
|
146
|
+
@app.get("/v1/stats")
|
|
147
|
+
def stats(p: Principal = Depends(need("read"))) -> dict:
|
|
148
|
+
return engine.stats(tenant_id=p.tenant_id)
|
|
149
|
+
|
|
150
|
+
@app.get("/v1/strategies")
|
|
151
|
+
def strategies(p: Principal = Depends(need("read"))) -> list[dict]:
|
|
152
|
+
return engine.strategy_report(p.tenant_id)
|
|
153
|
+
|
|
154
|
+
@app.get("/v1/usage")
|
|
155
|
+
def usage(p: Principal = Depends(need("read"))) -> list[dict]:
|
|
156
|
+
return engine.usage_by_provider()
|
|
157
|
+
|
|
158
|
+
# ---- write ---------------------------------------------------------------------------
|
|
159
|
+
@app.post("/v1/memories", status_code=201)
|
|
160
|
+
def remember(b: RememberBody, p: Principal = Depends(need("write"))) -> dict:
|
|
161
|
+
act_as(p, b.user_id)
|
|
162
|
+
r = engine.remember(
|
|
163
|
+
b.text, user_id=b.user_id, tenant_id=p.tenant_id, level=b.level, source_type=b.source_type, origin=b.origin,
|
|
164
|
+
category=b.category, effective_at=b.effective_at, reliability=b.reliability, verification=b.verification,
|
|
165
|
+
metadata=b.metadata, facts=b.facts, **scope_kw(b),
|
|
166
|
+
)
|
|
167
|
+
audit(p, "remember", r.memory_ids[0])
|
|
168
|
+
return r.model_dump()
|
|
169
|
+
|
|
170
|
+
@app.post("/v1/conversations", status_code=201)
|
|
171
|
+
def conversation(b: ConversationBody, p: Principal = Depends(need("write"))) -> list[dict]:
|
|
172
|
+
act_as(p, b.user_id)
|
|
173
|
+
res = engine.remember_conversation(b.messages, user_id=b.user_id, tenant_id=p.tenant_id, session_id=b.session_id, agent_id=b.agent_id, project_id=b.project_id)
|
|
174
|
+
audit(p, "remember_conversation", str(len(res)))
|
|
175
|
+
return [r.model_dump() for r in res]
|
|
176
|
+
|
|
177
|
+
@app.post("/v1/memories/json", status_code=201)
|
|
178
|
+
def remember_json(b: JsonBody, p: Principal = Depends(need("write"))) -> list[dict]:
|
|
179
|
+
act_as(p, b.user_id)
|
|
180
|
+
res = engine.remember_json(b.record, user_id=b.user_id, subject=b.subject, tenant_id=p.tenant_id, **scope_kw(b))
|
|
181
|
+
audit(p, "remember_json", str(len(res)))
|
|
182
|
+
return [r.model_dump() for r in res]
|
|
183
|
+
|
|
184
|
+
@app.patch("/v1/memories/{memory_id}")
|
|
185
|
+
def correct(memory_id: str, b: CorrectBody, p: Principal = Depends(need("write"))) -> dict:
|
|
186
|
+
act_as(p, b.user_id)
|
|
187
|
+
rec = engine.correct(memory_id, b.new_content, user_id=b.user_id, tenant_id=p.tenant_id, reason=b.reason)
|
|
188
|
+
audit(p, "correct", memory_id)
|
|
189
|
+
return rec.model_dump()
|
|
190
|
+
|
|
191
|
+
@app.post("/v1/memories/{memory_id}/verify")
|
|
192
|
+
def verify(memory_id: str, b: VerifyBody, p: Principal = Depends(need("write"))) -> dict:
|
|
193
|
+
act_as(p, b.user_id)
|
|
194
|
+
engine.verify(memory_id, b.status, user_id=b.user_id, tenant_id=p.tenant_id)
|
|
195
|
+
audit(p, "verify", memory_id)
|
|
196
|
+
return {"memory_id": memory_id, "verification": b.status}
|
|
197
|
+
|
|
198
|
+
@app.delete("/v1/memories/{memory_id}")
|
|
199
|
+
def forget(memory_id: str, user_id: str = Query(min_length=1, max_length=200), p: Principal = Depends(need("write"))) -> dict:
|
|
200
|
+
act_as(p, user_id)
|
|
201
|
+
n = engine.forget(memory_id, user_id=user_id, tenant_id=p.tenant_id)
|
|
202
|
+
audit(p, "forget", memory_id)
|
|
203
|
+
return {"deleted": n}
|
|
204
|
+
|
|
205
|
+
@app.delete("/v1/users/{user_id}")
|
|
206
|
+
def forget_user(user_id: str, p: Principal = Depends(need("admin"))) -> dict:
|
|
207
|
+
act_as(p, user_id)
|
|
208
|
+
n = engine.forget(user_id=user_id, tenant_id=p.tenant_id, everything=True)
|
|
209
|
+
audit(p, "forget_user", user_id)
|
|
210
|
+
return {"deleted": n}
|
|
211
|
+
|
|
212
|
+
@app.post("/v1/feedback")
|
|
213
|
+
def feedback(b: FeedbackBody, p: Principal = Depends(need("write"))) -> dict:
|
|
214
|
+
row = engine.db.one("SELECT tenant_id FROM retrieval_log WHERE id=?", (b.recall_id,))
|
|
215
|
+
if not row or row["tenant_id"] != p.tenant_id:
|
|
216
|
+
raise HTTPException(404, "not found")
|
|
217
|
+
engine.feedback(b.recall_id, correct=b.correct, relevance=b.relevance, comment=b.comment)
|
|
218
|
+
return {"ok": True}
|
|
219
|
+
|
|
220
|
+
@app.post("/v1/consolidate")
|
|
221
|
+
def consolidate(b: ConsolidateBody, p: Principal = Depends(need("write"))) -> dict:
|
|
222
|
+
act_as(p, b.user_id)
|
|
223
|
+
audit(p, "consolidate", b.user_id)
|
|
224
|
+
return engine.consolidate(user_id=b.user_id, tenant_id=p.tenant_id, mode="manual" if b.mode == "dry_run" else b.mode, dry_run=b.mode == "dry_run")
|
|
225
|
+
|
|
226
|
+
@app.post("/v1/consolidate/{run_id}/rollback")
|
|
227
|
+
def rollback(run_id: str, user_id: str = Query(min_length=1), p: Principal = Depends(need("write"))) -> dict:
|
|
228
|
+
act_as(p, user_id)
|
|
229
|
+
audit(p, "consolidation_rollback", run_id)
|
|
230
|
+
return engine.rollback_consolidation(run_id, user_id=user_id, tenant_id=p.tenant_id)
|
|
231
|
+
|
|
232
|
+
# ---- read ----------------------------------------------------------------------------
|
|
233
|
+
@app.post("/v1/recall")
|
|
234
|
+
def recall(b: RecallBody, p: Principal = Depends(need("read"))) -> dict:
|
|
235
|
+
act_as(p, b.user_id)
|
|
236
|
+
res = engine.recall(b.query, user_id=b.user_id, tenant_id=p.tenant_id, top_k=b.top_k, as_of=b.as_of, strategy=b.strategy, synthesize=b.synthesize, **scope_kw(b))
|
|
237
|
+
audit(p, "recall", res.recall_id)
|
|
238
|
+
return res.model_dump()
|
|
239
|
+
|
|
240
|
+
def scope_q(user_id: str = Query(min_length=1, max_length=200), agent_id: str | None = None, session_id: str | None = None, project_id: str | None = None) -> dict:
|
|
241
|
+
return {"user_id": user_id, "agent_id": agent_id, "session_id": session_id, "project_id": project_id}
|
|
242
|
+
|
|
243
|
+
@app.get("/v1/memories")
|
|
244
|
+
def list_memories(s: dict = Depends(scope_q), category: str | None = None, limit: int = Query(100, ge=1, le=1000), offset: int = Query(0, ge=0), p: Principal = Depends(need("read"))) -> list[dict]:
|
|
245
|
+
act_as(p, s["user_id"])
|
|
246
|
+
return [m.model_dump() for m in engine.list_memories(tenant_id=p.tenant_id, category=category, limit=limit, offset=offset, **s)]
|
|
247
|
+
|
|
248
|
+
@app.get("/v1/memories/{memory_id}")
|
|
249
|
+
def get_memory(memory_id: str, s: dict = Depends(scope_q), p: Principal = Depends(need("read"))) -> dict:
|
|
250
|
+
act_as(p, s["user_id"])
|
|
251
|
+
return engine.get(memory_id, tenant_id=p.tenant_id, **s).model_dump()
|
|
252
|
+
|
|
253
|
+
@app.get("/v1/memories/{memory_id}/history")
|
|
254
|
+
def memory_history(memory_id: str, s: dict = Depends(scope_q), p: Principal = Depends(need("read"))) -> dict:
|
|
255
|
+
act_as(p, s["user_id"])
|
|
256
|
+
return engine.history(memory_id, tenant_id=p.tenant_id, **{k: v for k, v in s.items()})
|
|
257
|
+
|
|
258
|
+
@app.get("/v1/history")
|
|
259
|
+
def value_history(subject: str, predicate: str, s: dict = Depends(scope_q), p: Principal = Depends(need("read"))) -> dict:
|
|
260
|
+
act_as(p, s["user_id"])
|
|
261
|
+
return engine.history(subject=subject, predicate=predicate, tenant_id=p.tenant_id, **s)
|
|
262
|
+
|
|
263
|
+
@app.get("/v1/explain/{recall_id}")
|
|
264
|
+
def explain(recall_id: str, user_id: str = Query(min_length=1), p: Principal = Depends(need("read"))) -> dict:
|
|
265
|
+
act_as(p, user_id)
|
|
266
|
+
return engine.explain(recall_id, user_id=user_id, tenant_id=p.tenant_id)
|
|
267
|
+
|
|
268
|
+
@app.get("/v1/facts")
|
|
269
|
+
def facts(s: dict = Depends(scope_q), as_of: str | None = None, p: Principal = Depends(need("read"))) -> list[dict]:
|
|
270
|
+
act_as(p, s["user_id"])
|
|
271
|
+
return [f.model_dump() for f in engine.facts(tenant_id=p.tenant_id, as_of=as_of, **{k: v for k, v in s.items() if k != "user_id"}, user_id=s["user_id"])]
|
|
272
|
+
|
|
273
|
+
@app.get("/v1/contradictions")
|
|
274
|
+
def contradictions(s: dict = Depends(scope_q), p: Principal = Depends(need("read"))) -> list[dict]:
|
|
275
|
+
act_as(p, s["user_id"])
|
|
276
|
+
return [c.model_dump() for c in engine.contradictions(tenant_id=p.tenant_id, **s)]
|
|
277
|
+
|
|
278
|
+
@app.get("/v1/snapshot")
|
|
279
|
+
def snapshot(as_of: str, s: dict = Depends(scope_q), p: Principal = Depends(need("read"))) -> dict:
|
|
280
|
+
act_as(p, s["user_id"])
|
|
281
|
+
return engine.snapshot(as_of, tenant_id=p.tenant_id, **s)
|
|
282
|
+
|
|
283
|
+
@app.get("/v1/changes")
|
|
284
|
+
def changes(since: str, user_id: str = Query(min_length=1), until: str | None = None, p: Principal = Depends(need("read"))) -> list[dict]:
|
|
285
|
+
act_as(p, user_id)
|
|
286
|
+
return engine.changes(since, until, user_id=user_id, tenant_id=p.tenant_id)
|
|
287
|
+
|
|
288
|
+
@app.get("/v1/graph")
|
|
289
|
+
def graph(s: dict = Depends(scope_q), as_of: str | None = None, p: Principal = Depends(need("read"))) -> dict:
|
|
290
|
+
act_as(p, s["user_id"])
|
|
291
|
+
return engine.graph(tenant_id=p.tenant_id, as_of=as_of, **s)
|
|
292
|
+
|
|
293
|
+
@app.get("/v1/consolidation/runs")
|
|
294
|
+
def runs(user_id: str = Query(min_length=1), p: Principal = Depends(need("read"))) -> list[dict]:
|
|
295
|
+
act_as(p, user_id)
|
|
296
|
+
return engine.consolidation_runs(user_id=user_id, tenant_id=p.tenant_id)
|
|
297
|
+
|
|
298
|
+
@app.get("/v1/recalls")
|
|
299
|
+
def recalls(user_id: str = Query(min_length=1), limit: int = Query(50, ge=1, le=500), p: Principal = Depends(need("read"))) -> list[dict]:
|
|
300
|
+
act_as(p, user_id)
|
|
301
|
+
return engine.recent_recalls(user_id=user_id, tenant_id=p.tenant_id, limit=limit)
|
|
302
|
+
|
|
303
|
+
@app.post("/v1/reflect")
|
|
304
|
+
def reflect(b: ScopeBody, topic: str | None = None, p: Principal = Depends(need("read"))) -> dict:
|
|
305
|
+
act_as(p, b.user_id)
|
|
306
|
+
return engine.reflect(user_id=b.user_id, tenant_id=p.tenant_id, topic=topic, **scope_kw(b))
|
|
307
|
+
|
|
308
|
+
@app.get("/v1/export")
|
|
309
|
+
def export(user_id: str = Query(min_length=1), p: Principal = Depends(need("read"))) -> dict:
|
|
310
|
+
act_as(p, user_id)
|
|
311
|
+
audit(p, "export", user_id)
|
|
312
|
+
return engine.export(user_id=user_id, tenant_id=p.tenant_id)
|
|
313
|
+
|
|
314
|
+
@app.get("/v1/benchmarks")
|
|
315
|
+
def benchmarks(p: Principal = Depends(need("read"))) -> list[dict]:
|
|
316
|
+
out = []
|
|
317
|
+
if reports.exists():
|
|
318
|
+
for f in sorted(reports.glob("*.json")):
|
|
319
|
+
try:
|
|
320
|
+
out.append(json.loads(f.read_text(encoding="utf-8")))
|
|
321
|
+
except ValueError:
|
|
322
|
+
continue
|
|
323
|
+
return out
|
|
324
|
+
|
|
325
|
+
return app
|
memoraos/api/auth.py
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"""API key authentication. Keys are stored only as SHA-256 hashes and bound to one tenant and role."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import hmac
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import secrets
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
ROLES = {"read": 1, "write": 2, "admin": 3}
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True)
|
|
17
|
+
class Principal:
|
|
18
|
+
tenant_id: str
|
|
19
|
+
role: str
|
|
20
|
+
users: tuple[str, ...] # ("*",) means any user id inside the tenant
|
|
21
|
+
fingerprint: str
|
|
22
|
+
|
|
23
|
+
def can(self, needed: str) -> bool:
|
|
24
|
+
return ROLES[self.role] >= ROLES[needed]
|
|
25
|
+
|
|
26
|
+
def may_act_as(self, user_id: str) -> bool:
|
|
27
|
+
return "*" in self.users or user_id in self.users
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _hash(key: str) -> str:
|
|
31
|
+
return hashlib.sha256(key.encode("utf-8")).hexdigest()
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class ApiKeyStore:
|
|
35
|
+
def __init__(self, entries: dict[str, dict] | None = None):
|
|
36
|
+
# entries: sha256(key) -> {tenant, role, users}
|
|
37
|
+
self._entries: dict[str, dict] = {}
|
|
38
|
+
for digest, spec in (entries or {}).items():
|
|
39
|
+
self._validate(spec)
|
|
40
|
+
self._entries[digest] = spec
|
|
41
|
+
|
|
42
|
+
@staticmethod
|
|
43
|
+
def _validate(spec: dict) -> None:
|
|
44
|
+
if spec.get("role") not in ROLES:
|
|
45
|
+
raise ValueError(f"role must be one of {sorted(ROLES)}")
|
|
46
|
+
if not spec.get("tenant"):
|
|
47
|
+
raise ValueError("tenant is required")
|
|
48
|
+
|
|
49
|
+
@classmethod
|
|
50
|
+
def from_plain(cls, keys: dict[str, dict]) -> ApiKeyStore:
|
|
51
|
+
return cls({_hash(k): v for k, v in keys.items()})
|
|
52
|
+
|
|
53
|
+
@classmethod
|
|
54
|
+
def load(cls, path: Path | None = None, env: str = "MEMORAOS_API_KEYS") -> ApiKeyStore:
|
|
55
|
+
entries: dict[str, dict] = {}
|
|
56
|
+
if path and Path(path).exists():
|
|
57
|
+
entries.update(json.loads(Path(path).read_text(encoding="utf-8")))
|
|
58
|
+
raw = os.environ.get(env)
|
|
59
|
+
if raw:
|
|
60
|
+
entries.update({_hash(k): v for k, v in json.loads(raw).items()})
|
|
61
|
+
return cls(entries)
|
|
62
|
+
|
|
63
|
+
def __len__(self) -> int:
|
|
64
|
+
return len(self._entries)
|
|
65
|
+
|
|
66
|
+
def authenticate(self, presented: str | None) -> Principal | None:
|
|
67
|
+
if not presented:
|
|
68
|
+
return None
|
|
69
|
+
digest = _hash(presented)
|
|
70
|
+
found = None
|
|
71
|
+
for stored, spec in self._entries.items(): # constant-time comparison across all entries
|
|
72
|
+
if hmac.compare_digest(stored, digest):
|
|
73
|
+
found = spec
|
|
74
|
+
if not found:
|
|
75
|
+
return None
|
|
76
|
+
return Principal(found["tenant"], found["role"], tuple(found.get("users", ["*"])), digest[:8])
|
|
77
|
+
|
|
78
|
+
@staticmethod
|
|
79
|
+
def create(path: Path, tenant: str, role: str = "write", users: list[str] | None = None) -> str:
|
|
80
|
+
"""Generate a key, persist only its hash, and return the plaintext once."""
|
|
81
|
+
spec = {"tenant": tenant, "role": role, "users": users or ["*"]}
|
|
82
|
+
ApiKeyStore._validate(spec)
|
|
83
|
+
key = "mos_" + secrets.token_urlsafe(32)
|
|
84
|
+
entries = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
|
|
85
|
+
entries[_hash(key)] = spec
|
|
86
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
87
|
+
path.write_text(json.dumps(entries, indent=2), encoding="utf-8")
|
|
88
|
+
return key
|
memoraos/cli.py
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
"""Command line interface."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
from . import __version__
|
|
12
|
+
from .config import Settings
|
|
13
|
+
from .engine import MemoryOS
|
|
14
|
+
from .storage.crypto import ENV_KEY, EncryptionError
|
|
15
|
+
from .storage.db import convert_database
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _engine(args: argparse.Namespace) -> MemoryOS:
|
|
19
|
+
try:
|
|
20
|
+
return MemoryOS.local(args.data_dir)
|
|
21
|
+
except EncryptionError as exc:
|
|
22
|
+
print(f"memoraos: {exc}", file=sys.stderr)
|
|
23
|
+
raise SystemExit(2) from exc
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _print(obj) -> None:
|
|
27
|
+
print(json.dumps(obj, indent=2, default=str, ensure_ascii=False))
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _ci(args: argparse.Namespace) -> int:
|
|
31
|
+
from . import contracts
|
|
32
|
+
|
|
33
|
+
try:
|
|
34
|
+
if args.ci_cmd == "compare":
|
|
35
|
+
base = json.loads(Path(args.baseline).read_text(encoding="utf-8"))
|
|
36
|
+
cur = json.loads(Path(args.current).read_text(encoding="utf-8"))
|
|
37
|
+
diff = contracts.compare(base, cur)
|
|
38
|
+
print(contracts.render(cur, diff))
|
|
39
|
+
return 0 if diff["ok"] and cur["passed"] else 1
|
|
40
|
+
doc = contracts.load_contract(args.contract)
|
|
41
|
+
settings = None
|
|
42
|
+
if args.set or args.embedder:
|
|
43
|
+
overrides = {**doc.get("settings", {})}
|
|
44
|
+
for item in args.set or []:
|
|
45
|
+
key, sep, raw = item.partition("=")
|
|
46
|
+
if not sep:
|
|
47
|
+
raise contracts.ContractError(f"--set expects key=value, got {item!r}")
|
|
48
|
+
try:
|
|
49
|
+
overrides[key] = json.loads(raw)
|
|
50
|
+
except json.JSONDecodeError:
|
|
51
|
+
overrides[key] = raw
|
|
52
|
+
settings = Settings(**overrides)
|
|
53
|
+
embedder = None
|
|
54
|
+
if args.embedder:
|
|
55
|
+
from .providers.embeddings import SentenceTransformerEmbedder
|
|
56
|
+
|
|
57
|
+
embedder = SentenceTransformerEmbedder(args.embedder)
|
|
58
|
+
result = contracts.run_contract(doc, settings=settings, embedder=embedder).to_dict()
|
|
59
|
+
diff = None
|
|
60
|
+
if args.baseline:
|
|
61
|
+
diff = contracts.compare(json.loads(Path(args.baseline).read_text(encoding="utf-8")), result)
|
|
62
|
+
if args.out:
|
|
63
|
+
Path(args.out).write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8")
|
|
64
|
+
print(contracts.render(result, diff))
|
|
65
|
+
return 0 if result["passed"] and (diff is None or diff["ok"]) else 1
|
|
66
|
+
except (contracts.ContractError, OSError, json.JSONDecodeError, KeyError, ValueError, ImportError) as exc:
|
|
67
|
+
print(f"memoraos ci: {exc}", file=sys.stderr)
|
|
68
|
+
return 2
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def main(argv: list[str] | None = None) -> int:
|
|
72
|
+
p = argparse.ArgumentParser(prog="memoraos", description="MemoraOS adaptive memory engine")
|
|
73
|
+
p.add_argument("--data-dir", default=None, help="data directory (default ./.memoraos)")
|
|
74
|
+
p.add_argument("--version", action="version", version=__version__)
|
|
75
|
+
sub = p.add_subparsers(dest="cmd", required=True)
|
|
76
|
+
|
|
77
|
+
r = sub.add_parser("remember", help="store text")
|
|
78
|
+
r.add_argument("text")
|
|
79
|
+
r.add_argument("--user", required=True)
|
|
80
|
+
r.add_argument("--effective-at")
|
|
81
|
+
q = sub.add_parser("recall", help="answer a question")
|
|
82
|
+
q.add_argument("query")
|
|
83
|
+
q.add_argument("--user", required=True)
|
|
84
|
+
q.add_argument("--as-of")
|
|
85
|
+
q.add_argument("--explain", action="store_true")
|
|
86
|
+
c = sub.add_parser("consolidate")
|
|
87
|
+
c.add_argument("--user", required=True)
|
|
88
|
+
c.add_argument("--mode", default="manual", choices=["manual", "incremental"])
|
|
89
|
+
c.add_argument("--dry-run", action="store_true")
|
|
90
|
+
s = sub.add_parser("stats")
|
|
91
|
+
s.add_argument("--tenant", default="default")
|
|
92
|
+
e = sub.add_parser("export")
|
|
93
|
+
e.add_argument("--user", required=True)
|
|
94
|
+
sub.add_parser("backup").add_argument("dest")
|
|
95
|
+
sub.add_parser("encrypt", help=f"encrypt the database file in place (passphrase from {ENV_KEY})")
|
|
96
|
+
sub.add_parser("decrypt", help=f"decrypt the database file in place (passphrase from {ENV_KEY})")
|
|
97
|
+
|
|
98
|
+
k = sub.add_parser("keys", help="manage API keys")
|
|
99
|
+
ks = k.add_subparsers(dest="keys_cmd", required=True)
|
|
100
|
+
kc = ks.add_parser("create")
|
|
101
|
+
kc.add_argument("--tenant", required=True)
|
|
102
|
+
kc.add_argument("--role", default="write", choices=["read", "write", "admin"])
|
|
103
|
+
kc.add_argument("--users", nargs="*", help="restrict the key to these user ids")
|
|
104
|
+
|
|
105
|
+
sv = sub.add_parser("serve", help="start the REST API")
|
|
106
|
+
sv.add_argument("--host", default="127.0.0.1")
|
|
107
|
+
sv.add_argument("--port", type=int, default=8000)
|
|
108
|
+
sv.add_argument("--insecure-no-auth", action="store_true", help="development only: disable authentication")
|
|
109
|
+
sub.add_parser("mcp", help="start the MCP stdio server (set MEMORAOS_USER_ID)")
|
|
110
|
+
|
|
111
|
+
b = sub.add_parser("bench", help="run the benchmark suite")
|
|
112
|
+
b.add_argument("--seed", type=int, default=7)
|
|
113
|
+
b.add_argument("--out", default="benchmarks/reports")
|
|
114
|
+
b.add_argument("--quick", action="store_true", help="smaller dataset for smoke runs")
|
|
115
|
+
|
|
116
|
+
ci = sub.add_parser("ci", help="Memory CI: run memory contracts and diff two runs")
|
|
117
|
+
cis = ci.add_subparsers(dest="ci_cmd", required=True)
|
|
118
|
+
cr = cis.add_parser("run", help="run a contract (JSON, or YAML with PyYAML); exit 1 on a failed assertion or regression")
|
|
119
|
+
cr.add_argument("contract")
|
|
120
|
+
cr.add_argument("--baseline", help="a previous --out file of the same contract; adds a regression report")
|
|
121
|
+
cr.add_argument("--out", help="write this run's result JSON here (use it as the next baseline)")
|
|
122
|
+
cr.add_argument("--set", action="append", metavar="KEY=VALUE", help='override a Settings field for this run, e.g. --set answerability=balanced (value is parsed as JSON when possible)')
|
|
123
|
+
cr.add_argument("--embedder", help="sentence-transformers model name to run the contract with (needs sentence-transformers); default is the offline hashing embedder")
|
|
124
|
+
cc = cis.add_parser("compare", help="regression report between two result files")
|
|
125
|
+
cc.add_argument("baseline")
|
|
126
|
+
cc.add_argument("current")
|
|
127
|
+
|
|
128
|
+
args = p.parse_args(argv)
|
|
129
|
+
|
|
130
|
+
if args.cmd == "ci":
|
|
131
|
+
return _ci(args)
|
|
132
|
+
if args.cmd in ("encrypt", "decrypt"):
|
|
133
|
+
passphrase = os.environ.get(ENV_KEY)
|
|
134
|
+
if not passphrase:
|
|
135
|
+
print(f"Set {ENV_KEY} (a passphrase is never accepted on the command line).", file=sys.stderr)
|
|
136
|
+
return 2
|
|
137
|
+
db_file = Settings(data_dir=Path(args.data_dir or ".memoraos")).db_path
|
|
138
|
+
try:
|
|
139
|
+
convert_database(db_file, passphrase, to_encrypted=args.cmd == "encrypt")
|
|
140
|
+
except (EncryptionError, OSError) as exc:
|
|
141
|
+
print(f"memoraos {args.cmd}: {exc}", file=sys.stderr)
|
|
142
|
+
return 2
|
|
143
|
+
print(f"{db_file}: {args.cmd}ed. Plain copies under 'sources/' and old backups are not touched; remove them if they are sensitive.")
|
|
144
|
+
return 0
|
|
145
|
+
if args.cmd == "keys":
|
|
146
|
+
data = Path(args.data_dir or ".memoraos")
|
|
147
|
+
from .api.auth import ApiKeyStore
|
|
148
|
+
|
|
149
|
+
key = ApiKeyStore.create(data / "api_keys.json", args.tenant, args.role, args.users)
|
|
150
|
+
print(f"API key (shown once, store it securely):\n{key}")
|
|
151
|
+
return 0
|
|
152
|
+
if args.cmd == "serve":
|
|
153
|
+
try:
|
|
154
|
+
import uvicorn
|
|
155
|
+
|
|
156
|
+
from .api.app import create_app
|
|
157
|
+
from .api.auth import ApiKeyStore
|
|
158
|
+
except ImportError:
|
|
159
|
+
print("Install the API extra: pip install 'memoraos[api]'", file=sys.stderr)
|
|
160
|
+
return 2
|
|
161
|
+
eng = _engine(args)
|
|
162
|
+
keys = ApiKeyStore.load(eng.settings.data_dir / "api_keys.json")
|
|
163
|
+
try:
|
|
164
|
+
app = create_app(eng, keys, insecure_no_auth=args.insecure_no_auth)
|
|
165
|
+
except RuntimeError as exc:
|
|
166
|
+
print(str(exc), file=sys.stderr)
|
|
167
|
+
return 2
|
|
168
|
+
uvicorn.run(app, host=args.host, port=args.port)
|
|
169
|
+
return 0
|
|
170
|
+
if args.cmd == "mcp":
|
|
171
|
+
from .mcp.server import main as mcp_main
|
|
172
|
+
|
|
173
|
+
mcp_main()
|
|
174
|
+
return 0
|
|
175
|
+
if args.cmd == "bench":
|
|
176
|
+
try:
|
|
177
|
+
from benchmarks.run import main as bench_main # type: ignore[import-not-found]
|
|
178
|
+
except ImportError:
|
|
179
|
+
print("The benchmark lab lives in the source repository: run `python -m benchmarks.run` from a checkout.", file=sys.stderr)
|
|
180
|
+
return 2
|
|
181
|
+
return bench_main(["--seed", str(args.seed), "--out", args.out] + (["--quick"] if args.quick else []))
|
|
182
|
+
|
|
183
|
+
eng = _engine(args)
|
|
184
|
+
try:
|
|
185
|
+
if args.cmd == "remember":
|
|
186
|
+
_print(eng.remember(args.text, user_id=args.user, effective_at=args.effective_at).model_dump())
|
|
187
|
+
elif args.cmd == "recall":
|
|
188
|
+
res = eng.recall(args.query, user_id=args.user, as_of=args.as_of)
|
|
189
|
+
_print(res.model_dump())
|
|
190
|
+
if args.explain:
|
|
191
|
+
_print(eng.explain(res.recall_id, user_id=args.user))
|
|
192
|
+
elif args.cmd == "consolidate":
|
|
193
|
+
_print(eng.consolidate(user_id=args.user, mode=args.mode, dry_run=args.dry_run))
|
|
194
|
+
elif args.cmd == "stats":
|
|
195
|
+
_print(eng.stats(tenant_id=args.tenant))
|
|
196
|
+
elif args.cmd == "export":
|
|
197
|
+
_print(eng.export(user_id=args.user))
|
|
198
|
+
elif args.cmd == "backup":
|
|
199
|
+
print(eng.backup(args.dest))
|
|
200
|
+
finally:
|
|
201
|
+
eng.close()
|
|
202
|
+
return 0
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
if __name__ == "__main__":
|
|
206
|
+
raise SystemExit(main())
|