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.
Files changed (73) hide show
  1. memoraos/__init__.py +8 -0
  2. memoraos/api/__init__.py +9 -0
  3. memoraos/api/app.py +325 -0
  4. memoraos/api/auth.py +88 -0
  5. memoraos/cli.py +206 -0
  6. memoraos/client.py +66 -0
  7. memoraos/config.py +184 -0
  8. memoraos/consolidation/__init__.py +3 -0
  9. memoraos/consolidation/engine.py +369 -0
  10. memoraos/contracts.py +247 -0
  11. memoraos/engine.py +836 -0
  12. memoraos/evaluation/__init__.py +4 -0
  13. memoraos/evaluation/metrics.py +54 -0
  14. memoraos/evaluation/runner.py +58 -0
  15. memoraos/extraction/__init__.py +23 -0
  16. memoraos/extraction/base.py +43 -0
  17. memoraos/extraction/llm.py +187 -0
  18. memoraos/extraction/pipeline.py +93 -0
  19. memoraos/extraction/rules.py +27 -0
  20. memoraos/extraction/schema.py +36 -0
  21. memoraos/extraction/validate.py +112 -0
  22. memoraos/extraction/values.py +133 -0
  23. memoraos/fusion/__init__.py +27 -0
  24. memoraos/fusion/paths.py +238 -0
  25. memoraos/fusion/plan.py +118 -0
  26. memoraos/ingestion/__init__.py +15 -0
  27. memoraos/ingestion/classify.py +75 -0
  28. memoraos/ingestion/dates.py +170 -0
  29. memoraos/ingestion/extract.py +315 -0
  30. memoraos/ingestion/lexicon.py +90 -0
  31. memoraos/latent/__init__.py +20 -0
  32. memoraos/latent/base.py +73 -0
  33. memoraos/latent/index.py +76 -0
  34. memoraos/latent/slots.py +91 -0
  35. memoraos/mcp/__init__.py +3 -0
  36. memoraos/mcp/server.py +131 -0
  37. memoraos/models.py +187 -0
  38. memoraos/providers/__init__.py +49 -0
  39. memoraos/providers/base.py +70 -0
  40. memoraos/providers/embeddings.py +162 -0
  41. memoraos/providers/http.py +248 -0
  42. memoraos/providers/local.py +79 -0
  43. memoraos/providers/rerank.py +87 -0
  44. memoraos/recall.py +927 -0
  45. memoraos/retrieval/__init__.py +5 -0
  46. memoraos/retrieval/ann.py +59 -0
  47. memoraos/retrieval/answer_type.py +38 -0
  48. memoraos/retrieval/entity.py +115 -0
  49. memoraos/retrieval/expand.py +117 -0
  50. memoraos/retrieval/facts.py +211 -0
  51. memoraos/retrieval/fusion.py +59 -0
  52. memoraos/retrieval/graph.py +153 -0
  53. memoraos/retrieval/lexical.py +79 -0
  54. memoraos/retrieval/vector.py +93 -0
  55. memoraos/routing/__init__.py +14 -0
  56. memoraos/routing/learning.py +77 -0
  57. memoraos/routing/router.py +254 -0
  58. memoraos/security.py +87 -0
  59. memoraos/storage/__init__.py +4 -0
  60. memoraos/storage/crypto.py +79 -0
  61. memoraos/storage/db.py +401 -0
  62. memoraos/storage/visibility.py +41 -0
  63. memoraos/store.py +333 -0
  64. memoraos/truth/__init__.py +3 -0
  65. memoraos/truth/answer.py +252 -0
  66. memoraos/truth/timeline.py +225 -0
  67. memoraos/util.py +105 -0
  68. memoraos-0.2.0.dist-info/METADATA +405 -0
  69. memoraos-0.2.0.dist-info/RECORD +73 -0
  70. memoraos-0.2.0.dist-info/WHEEL +5 -0
  71. memoraos-0.2.0.dist-info/entry_points.txt +2 -0
  72. memoraos-0.2.0.dist-info/licenses/LICENSE +202 -0
  73. 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__"]
@@ -0,0 +1,9 @@
1
+ from .auth import ApiKeyStore, Principal
2
+
3
+ __all__ = ["ApiKeyStore", "Principal", "create_app"]
4
+
5
+
6
+ def create_app(*args, **kwargs): # lazy import keeps FastAPI optional
7
+ from .app import create_app as _create
8
+
9
+ return _create(*args, **kwargs)
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())