remembr 0.1.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.
- remembr/__init__.py +19 -0
- remembr/client.py +495 -0
- remembr/exceptions.py +49 -0
- remembr/models.py +48 -0
- remembr-0.1.0.dist-info/METADATA +393 -0
- remembr-0.1.0.dist-info/RECORD +9 -0
- remembr-0.1.0.dist-info/WHEEL +5 -0
- remembr-0.1.0.dist-info/licenses/LICENSE +21 -0
- remembr-0.1.0.dist-info/top_level.txt +1 -0
remembr/__init__.py
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Remembr Python SDK public exports."""
|
|
2
|
+
|
|
3
|
+
from .client import RemembrClient
|
|
4
|
+
from .exceptions import AuthenticationError, NotFoundError, RateLimitError, RemembrError, ServerError
|
|
5
|
+
from .models import CheckpointInfo, Episode, MemoryQueryResult, SearchResult, Session
|
|
6
|
+
|
|
7
|
+
__all__ = [
|
|
8
|
+
"RemembrClient",
|
|
9
|
+
"RemembrError",
|
|
10
|
+
"AuthenticationError",
|
|
11
|
+
"NotFoundError",
|
|
12
|
+
"RateLimitError",
|
|
13
|
+
"ServerError",
|
|
14
|
+
"Session",
|
|
15
|
+
"Episode",
|
|
16
|
+
"SearchResult",
|
|
17
|
+
"MemoryQueryResult",
|
|
18
|
+
"CheckpointInfo",
|
|
19
|
+
]
|
remembr/client.py
ADDED
|
@@ -0,0 +1,495 @@
|
|
|
1
|
+
"""Core Remembr SDK client implementation."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import os
|
|
7
|
+
from datetime import datetime
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
import httpx
|
|
11
|
+
from tenacity import AsyncRetrying, retry_if_exception_type, stop_after_attempt, wait_exponential
|
|
12
|
+
|
|
13
|
+
from .exceptions import AuthenticationError, NotFoundError, RateLimitError, RemembrError, ServerError
|
|
14
|
+
from .models import CheckpointInfo, Episode, MemoryQueryResult, Session
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class _RetryableServerError(ServerError):
|
|
18
|
+
"""Internal exception used to trigger retries for transient failures."""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class RemembrClient:
|
|
22
|
+
"""Remembr API client with async-first APIs and sync wrappers."""
|
|
23
|
+
|
|
24
|
+
VALID_SEARCH_MODES = {"semantic", "hybrid", "filter_only"}
|
|
25
|
+
|
|
26
|
+
def __init__(
|
|
27
|
+
self,
|
|
28
|
+
api_key: str | None = None,
|
|
29
|
+
base_url: str = "http://localhost:8000/api/v1",
|
|
30
|
+
timeout: float = 30,
|
|
31
|
+
) -> None:
|
|
32
|
+
resolved_api_key = api_key or os.getenv("REMEMBR_API_KEY")
|
|
33
|
+
if not resolved_api_key:
|
|
34
|
+
raise AuthenticationError(
|
|
35
|
+
"Missing API key. Pass `api_key=` or set REMEMBR_API_KEY environment variable."
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
self.api_key = resolved_api_key
|
|
39
|
+
self.base_url = base_url.rstrip("/")
|
|
40
|
+
self.timeout = timeout
|
|
41
|
+
self._client: httpx.AsyncClient | None = None
|
|
42
|
+
|
|
43
|
+
async def __aenter__(self) -> "RemembrClient":
|
|
44
|
+
await self._ensure_client()
|
|
45
|
+
return self
|
|
46
|
+
|
|
47
|
+
async def __aexit__(self, exc_type, exc, tb) -> None: # type: ignore[override]
|
|
48
|
+
await self.aclose()
|
|
49
|
+
|
|
50
|
+
async def _ensure_client(self) -> httpx.AsyncClient:
|
|
51
|
+
if self._client is None:
|
|
52
|
+
self._client = httpx.AsyncClient(
|
|
53
|
+
base_url=self.base_url,
|
|
54
|
+
timeout=httpx.Timeout(self.timeout),
|
|
55
|
+
headers={
|
|
56
|
+
"Authorization": f"Bearer {self.api_key}",
|
|
57
|
+
"Accept": "application/json",
|
|
58
|
+
"Content-Type": "application/json",
|
|
59
|
+
},
|
|
60
|
+
)
|
|
61
|
+
return self._client
|
|
62
|
+
|
|
63
|
+
async def aclose(self) -> None:
|
|
64
|
+
"""Close underlying HTTP resources for the async client."""
|
|
65
|
+
if self._client is not None:
|
|
66
|
+
await self._client.aclose()
|
|
67
|
+
self._client = None
|
|
68
|
+
|
|
69
|
+
async def arequest(
|
|
70
|
+
self,
|
|
71
|
+
method: str,
|
|
72
|
+
path: str,
|
|
73
|
+
*,
|
|
74
|
+
params: dict[str, Any] | None = None,
|
|
75
|
+
json: dict[str, Any] | None = None,
|
|
76
|
+
) -> dict[str, Any]:
|
|
77
|
+
"""Perform a raw API request and return the `data` payload.
|
|
78
|
+
|
|
79
|
+
Args:
|
|
80
|
+
method: HTTP method name, such as ``"GET"`` or ``"POST"``.
|
|
81
|
+
path: API path relative to ``base_url``.
|
|
82
|
+
params: Optional query parameters.
|
|
83
|
+
json: Optional JSON request body.
|
|
84
|
+
|
|
85
|
+
Returns:
|
|
86
|
+
The deserialized response payload (typically the API `data` object).
|
|
87
|
+
"""
|
|
88
|
+
client = await self._ensure_client()
|
|
89
|
+
|
|
90
|
+
try:
|
|
91
|
+
async for attempt in AsyncRetrying(
|
|
92
|
+
stop=stop_after_attempt(4), # initial + 3 retries
|
|
93
|
+
wait=wait_exponential(multiplier=1, min=1, max=4),
|
|
94
|
+
retry=retry_if_exception_type((_RetryableServerError, httpx.TimeoutException)),
|
|
95
|
+
reraise=True,
|
|
96
|
+
):
|
|
97
|
+
with attempt:
|
|
98
|
+
response = await client.request(method=method, url=path, params=params, json=json)
|
|
99
|
+
if response.status_code == 429 or 500 <= response.status_code <= 599:
|
|
100
|
+
exc = self._to_exception(response)
|
|
101
|
+
raise _RetryableServerError(
|
|
102
|
+
str(exc),
|
|
103
|
+
status_code=response.status_code,
|
|
104
|
+
code=getattr(exc, "code", None),
|
|
105
|
+
details=getattr(exc, "details", None),
|
|
106
|
+
request_id=getattr(exc, "request_id", None),
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
if response.status_code >= 400:
|
|
110
|
+
raise self._to_exception(response)
|
|
111
|
+
|
|
112
|
+
try:
|
|
113
|
+
body = response.json()
|
|
114
|
+
except ValueError as err:
|
|
115
|
+
raise ServerError(
|
|
116
|
+
"Failed to parse JSON response from Remembr API.",
|
|
117
|
+
status_code=response.status_code,
|
|
118
|
+
) from err
|
|
119
|
+
|
|
120
|
+
if isinstance(body, dict) and "data" in body:
|
|
121
|
+
return body["data"]
|
|
122
|
+
|
|
123
|
+
if isinstance(body, dict):
|
|
124
|
+
return body
|
|
125
|
+
|
|
126
|
+
raise ServerError(
|
|
127
|
+
"Unexpected response type returned by Remembr API.",
|
|
128
|
+
status_code=response.status_code,
|
|
129
|
+
)
|
|
130
|
+
except httpx.TimeoutException as err:
|
|
131
|
+
raise ServerError("Request to Remembr API timed out.", code="TIMEOUT") from err
|
|
132
|
+
except _RetryableServerError as err:
|
|
133
|
+
if err.status_code == 429:
|
|
134
|
+
raise RateLimitError(
|
|
135
|
+
err.message,
|
|
136
|
+
status_code=err.status_code,
|
|
137
|
+
code=err.code,
|
|
138
|
+
details=err.details,
|
|
139
|
+
request_id=err.request_id,
|
|
140
|
+
) from err
|
|
141
|
+
raise ServerError(
|
|
142
|
+
err.message,
|
|
143
|
+
status_code=err.status_code,
|
|
144
|
+
code=err.code,
|
|
145
|
+
details=err.details,
|
|
146
|
+
request_id=err.request_id,
|
|
147
|
+
) from err
|
|
148
|
+
except httpx.HTTPError as err:
|
|
149
|
+
raise ServerError("HTTP communication error with Remembr API.") from err
|
|
150
|
+
|
|
151
|
+
def request(
|
|
152
|
+
self,
|
|
153
|
+
method: str,
|
|
154
|
+
path: str,
|
|
155
|
+
*,
|
|
156
|
+
params: dict[str, Any] | None = None,
|
|
157
|
+
json: dict[str, Any] | None = None,
|
|
158
|
+
) -> dict[str, Any]:
|
|
159
|
+
"""Synchronous wrapper over :meth:`arequest` using ``asyncio.run()``.
|
|
160
|
+
|
|
161
|
+
Args:
|
|
162
|
+
method: HTTP method name, such as ``"GET"`` or ``"POST"``.
|
|
163
|
+
path: API path relative to ``base_url``.
|
|
164
|
+
params: Optional query parameters.
|
|
165
|
+
json: Optional JSON request body.
|
|
166
|
+
|
|
167
|
+
Returns:
|
|
168
|
+
The deserialized response payload (typically the API `data` object).
|
|
169
|
+
"""
|
|
170
|
+
return asyncio.run(self.arequest(method, path, params=params, json=json))
|
|
171
|
+
|
|
172
|
+
async def create_session(self, metadata: dict[str, Any] | None = None) -> Session:
|
|
173
|
+
"""Create a new memory session.
|
|
174
|
+
|
|
175
|
+
Args:
|
|
176
|
+
metadata: Optional metadata dictionary stored alongside the created session.
|
|
177
|
+
|
|
178
|
+
Returns:
|
|
179
|
+
A :class:`~remembr.models.Session` object describing the newly created session.
|
|
180
|
+
"""
|
|
181
|
+
payload = {"metadata": metadata or {}}
|
|
182
|
+
data = await self.arequest("POST", "/sessions", json=payload)
|
|
183
|
+
return Session.model_validate(data)
|
|
184
|
+
|
|
185
|
+
async def get_session(self, session_id: str) -> Session:
|
|
186
|
+
"""Fetch metadata for a session by ID.
|
|
187
|
+
|
|
188
|
+
Args:
|
|
189
|
+
session_id: The target session identifier.
|
|
190
|
+
|
|
191
|
+
Returns:
|
|
192
|
+
A :class:`~remembr.models.Session` object containing session details.
|
|
193
|
+
"""
|
|
194
|
+
self._require_non_empty(session_id, "session_id")
|
|
195
|
+
data = await self.arequest("GET", f"/sessions/{session_id}")
|
|
196
|
+
session_data = data.get("session") if isinstance(data, dict) else None
|
|
197
|
+
if not isinstance(session_data, dict):
|
|
198
|
+
raise ServerError("Invalid session payload returned by Remembr API.")
|
|
199
|
+
|
|
200
|
+
return Session.model_validate(
|
|
201
|
+
{
|
|
202
|
+
"request_id": str(data.get("request_id", "")),
|
|
203
|
+
"session_id": session_data.get("session_id"),
|
|
204
|
+
"org_id": session_data.get("org_id"),
|
|
205
|
+
"created_at": session_data.get("created_at"),
|
|
206
|
+
"metadata": session_data.get("metadata"),
|
|
207
|
+
}
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
async def list_sessions(self, limit: int = 20, offset: int = 0) -> list[Session]:
|
|
211
|
+
"""List sessions for the authenticated scope.
|
|
212
|
+
|
|
213
|
+
Args:
|
|
214
|
+
limit: Maximum number of sessions to return.
|
|
215
|
+
offset: Number of sessions to skip before returning results.
|
|
216
|
+
|
|
217
|
+
Returns:
|
|
218
|
+
A list of :class:`~remembr.models.Session` objects.
|
|
219
|
+
"""
|
|
220
|
+
self._validate_pagination(limit=limit, offset=offset)
|
|
221
|
+
data = await self.arequest("GET", "/sessions", params={"limit": limit, "offset": offset})
|
|
222
|
+
sessions = data.get("sessions") if isinstance(data, dict) else None
|
|
223
|
+
if not isinstance(sessions, list):
|
|
224
|
+
raise ServerError("Invalid session list payload returned by Remembr API.")
|
|
225
|
+
|
|
226
|
+
request_id = str(data.get("request_id", ""))
|
|
227
|
+
org_id = str(data.get("org_id", ""))
|
|
228
|
+
return [
|
|
229
|
+
Session.model_validate(
|
|
230
|
+
{
|
|
231
|
+
"request_id": request_id,
|
|
232
|
+
"session_id": item.get("session_id"),
|
|
233
|
+
"org_id": org_id,
|
|
234
|
+
"created_at": item.get("created_at"),
|
|
235
|
+
"metadata": item.get("metadata"),
|
|
236
|
+
}
|
|
237
|
+
)
|
|
238
|
+
for item in sessions
|
|
239
|
+
if isinstance(item, dict)
|
|
240
|
+
]
|
|
241
|
+
|
|
242
|
+
async def store(
|
|
243
|
+
self,
|
|
244
|
+
content: str,
|
|
245
|
+
role: str = "user",
|
|
246
|
+
session_id: str | None = None,
|
|
247
|
+
tags: list[str] | None = None,
|
|
248
|
+
metadata: dict[str, Any] | None = None,
|
|
249
|
+
) -> Episode:
|
|
250
|
+
"""Store a memory episode.
|
|
251
|
+
|
|
252
|
+
Args:
|
|
253
|
+
content: Episode content text to persist.
|
|
254
|
+
role: Role label (for example ``"user"`` or ``"assistant"``).
|
|
255
|
+
session_id: Optional session ID to associate with the episode.
|
|
256
|
+
tags: Optional list of string tags.
|
|
257
|
+
metadata: Optional metadata dictionary for the episode.
|
|
258
|
+
|
|
259
|
+
Returns:
|
|
260
|
+
An :class:`~remembr.models.Episode` describing the stored memory.
|
|
261
|
+
"""
|
|
262
|
+
self._require_non_empty(content, "content")
|
|
263
|
+
self._require_non_empty(role, "role")
|
|
264
|
+
if session_id is not None:
|
|
265
|
+
self._require_non_empty(session_id, "session_id")
|
|
266
|
+
|
|
267
|
+
payload: dict[str, Any] = {
|
|
268
|
+
"content": content,
|
|
269
|
+
"role": role,
|
|
270
|
+
"tags": tags or [],
|
|
271
|
+
"metadata": metadata or {},
|
|
272
|
+
}
|
|
273
|
+
if session_id:
|
|
274
|
+
payload["session_id"] = session_id
|
|
275
|
+
|
|
276
|
+
data = await self.arequest("POST", "/memory", json=payload)
|
|
277
|
+
return Episode.model_validate(
|
|
278
|
+
{
|
|
279
|
+
"episode_id": data.get("episode_id"),
|
|
280
|
+
"session_id": data.get("session_id"),
|
|
281
|
+
"role": role,
|
|
282
|
+
"content": content,
|
|
283
|
+
"created_at": data.get("created_at"),
|
|
284
|
+
"tags": tags or [],
|
|
285
|
+
"metadata": metadata,
|
|
286
|
+
}
|
|
287
|
+
)
|
|
288
|
+
|
|
289
|
+
async def search(
|
|
290
|
+
self,
|
|
291
|
+
query: str,
|
|
292
|
+
session_id: str | None = None,
|
|
293
|
+
tags: list[str] | None = None,
|
|
294
|
+
from_time: datetime | None = None,
|
|
295
|
+
to_time: datetime | None = None,
|
|
296
|
+
limit: int = 20,
|
|
297
|
+
mode: str = "hybrid",
|
|
298
|
+
) -> MemoryQueryResult:
|
|
299
|
+
"""Search memory episodes.
|
|
300
|
+
|
|
301
|
+
Args:
|
|
302
|
+
query: Search text query.
|
|
303
|
+
session_id: Optional session ID to scope the search.
|
|
304
|
+
tags: Optional list of tags to filter by.
|
|
305
|
+
from_time: Optional lower timestamp bound (inclusive).
|
|
306
|
+
to_time: Optional upper timestamp bound (inclusive).
|
|
307
|
+
limit: Maximum number of search results to return.
|
|
308
|
+
mode: Search mode, one of ``semantic``, ``hybrid``, or ``filter_only``.
|
|
309
|
+
|
|
310
|
+
Returns:
|
|
311
|
+
A :class:`~remembr.models.MemoryQueryResult` object with matches and metadata.
|
|
312
|
+
"""
|
|
313
|
+
self._require_non_empty(query, "query")
|
|
314
|
+
if session_id is not None:
|
|
315
|
+
self._require_non_empty(session_id, "session_id")
|
|
316
|
+
if limit < 1:
|
|
317
|
+
raise ValueError("limit must be greater than 0")
|
|
318
|
+
if mode not in self.VALID_SEARCH_MODES:
|
|
319
|
+
raise ValueError("mode must be one of: semantic, hybrid, filter_only")
|
|
320
|
+
if from_time and to_time and from_time > to_time:
|
|
321
|
+
raise ValueError("from_time must be less than or equal to to_time")
|
|
322
|
+
|
|
323
|
+
payload: dict[str, Any] = {
|
|
324
|
+
"query": query,
|
|
325
|
+
"tags": tags,
|
|
326
|
+
"limit": limit,
|
|
327
|
+
"mode": mode,
|
|
328
|
+
}
|
|
329
|
+
if session_id:
|
|
330
|
+
payload["session_id"] = session_id
|
|
331
|
+
if from_time is not None:
|
|
332
|
+
payload["from_time"] = from_time.isoformat()
|
|
333
|
+
if to_time is not None:
|
|
334
|
+
payload["to_time"] = to_time.isoformat()
|
|
335
|
+
|
|
336
|
+
data = await self.arequest("POST", "/memory/search", json=payload)
|
|
337
|
+
return MemoryQueryResult.model_validate(data)
|
|
338
|
+
|
|
339
|
+
async def get_session_history(self, session_id: str, limit: int = 50) -> list[Episode]:
|
|
340
|
+
"""Retrieve stored episodes for a given session.
|
|
341
|
+
|
|
342
|
+
Args:
|
|
343
|
+
session_id: The session identifier.
|
|
344
|
+
limit: Maximum number of episodes to return.
|
|
345
|
+
|
|
346
|
+
Returns:
|
|
347
|
+
A list of :class:`~remembr.models.Episode` objects in API response order.
|
|
348
|
+
"""
|
|
349
|
+
self._require_non_empty(session_id, "session_id")
|
|
350
|
+
if limit < 1:
|
|
351
|
+
raise ValueError("limit must be greater than 0")
|
|
352
|
+
|
|
353
|
+
data = await self.arequest("GET", f"/sessions/{session_id}/history", params={"limit": limit})
|
|
354
|
+
episodes = data.get("episodes") if isinstance(data, dict) else None
|
|
355
|
+
if not isinstance(episodes, list):
|
|
356
|
+
raise ServerError("Invalid session history payload returned by Remembr API.")
|
|
357
|
+
return [Episode.model_validate(item) for item in episodes if isinstance(item, dict)]
|
|
358
|
+
|
|
359
|
+
async def checkpoint(self, session_id: str) -> CheckpointInfo:
|
|
360
|
+
"""Create a checkpoint for a session context window.
|
|
361
|
+
|
|
362
|
+
Args:
|
|
363
|
+
session_id: Session identifier for which to create a checkpoint.
|
|
364
|
+
|
|
365
|
+
Returns:
|
|
366
|
+
A :class:`~remembr.models.CheckpointInfo` for the created checkpoint.
|
|
367
|
+
"""
|
|
368
|
+
self._require_non_empty(session_id, "session_id")
|
|
369
|
+
data = await self.arequest("POST", f"/sessions/{session_id}/checkpoint")
|
|
370
|
+
return CheckpointInfo.model_validate(data)
|
|
371
|
+
|
|
372
|
+
async def restore(self, session_id: str, checkpoint_id: str) -> dict[str, Any]:
|
|
373
|
+
"""Restore a session's short-term context from a checkpoint.
|
|
374
|
+
|
|
375
|
+
Args:
|
|
376
|
+
session_id: Session identifier to restore.
|
|
377
|
+
checkpoint_id: Checkpoint identifier to restore from.
|
|
378
|
+
|
|
379
|
+
Returns:
|
|
380
|
+
A dictionary containing restore details from the API.
|
|
381
|
+
"""
|
|
382
|
+
self._require_non_empty(session_id, "session_id")
|
|
383
|
+
self._require_non_empty(checkpoint_id, "checkpoint_id")
|
|
384
|
+
return await self.arequest(
|
|
385
|
+
"POST",
|
|
386
|
+
f"/sessions/{session_id}/restore",
|
|
387
|
+
json={"checkpoint_id": checkpoint_id},
|
|
388
|
+
)
|
|
389
|
+
|
|
390
|
+
async def list_checkpoints(self, session_id: str) -> list[CheckpointInfo]:
|
|
391
|
+
"""List available checkpoints for a session.
|
|
392
|
+
|
|
393
|
+
Args:
|
|
394
|
+
session_id: Session identifier to inspect.
|
|
395
|
+
|
|
396
|
+
Returns:
|
|
397
|
+
A list of :class:`~remembr.models.CheckpointInfo` entries.
|
|
398
|
+
"""
|
|
399
|
+
self._require_non_empty(session_id, "session_id")
|
|
400
|
+
data = await self.arequest("GET", f"/sessions/{session_id}/checkpoints")
|
|
401
|
+
checkpoints = data.get("checkpoints") if isinstance(data, dict) else None
|
|
402
|
+
if not isinstance(checkpoints, list):
|
|
403
|
+
raise ServerError("Invalid checkpoint list payload returned by Remembr API.")
|
|
404
|
+
return [CheckpointInfo.model_validate(item) for item in checkpoints if isinstance(item, dict)]
|
|
405
|
+
|
|
406
|
+
async def forget_episode(self, episode_id: str) -> dict[str, Any]:
|
|
407
|
+
"""Delete a single memory episode.
|
|
408
|
+
|
|
409
|
+
Args:
|
|
410
|
+
episode_id: Episode identifier to delete.
|
|
411
|
+
|
|
412
|
+
Returns:
|
|
413
|
+
A dictionary confirming deletion details.
|
|
414
|
+
"""
|
|
415
|
+
self._require_non_empty(episode_id, "episode_id")
|
|
416
|
+
return await self.arequest("DELETE", f"/memory/{episode_id}")
|
|
417
|
+
|
|
418
|
+
async def forget_session(self, session_id: str) -> dict[str, Any]:
|
|
419
|
+
"""Delete all memory episodes in a session.
|
|
420
|
+
|
|
421
|
+
Args:
|
|
422
|
+
session_id: Session identifier whose memories should be removed.
|
|
423
|
+
|
|
424
|
+
Returns:
|
|
425
|
+
A dictionary summarizing deleted episode count.
|
|
426
|
+
"""
|
|
427
|
+
self._require_non_empty(session_id, "session_id")
|
|
428
|
+
return await self.arequest("DELETE", f"/memory/session/{session_id}")
|
|
429
|
+
|
|
430
|
+
async def forget_user(self, user_id: str) -> dict[str, Any]:
|
|
431
|
+
"""Delete all memories and sessions for a user (org-scoped operation).
|
|
432
|
+
|
|
433
|
+
Args:
|
|
434
|
+
user_id: User identifier whose memory data should be removed.
|
|
435
|
+
|
|
436
|
+
Returns:
|
|
437
|
+
A dictionary summarizing deleted sessions and episodes.
|
|
438
|
+
"""
|
|
439
|
+
self._require_non_empty(user_id, "user_id")
|
|
440
|
+
return await self.arequest("DELETE", f"/memory/user/{user_id}")
|
|
441
|
+
|
|
442
|
+
@staticmethod
|
|
443
|
+
def _require_non_empty(value: str, param_name: str) -> None:
|
|
444
|
+
if not isinstance(value, str) or not value.strip():
|
|
445
|
+
raise ValueError(f"{param_name} is required and must be a non-empty string")
|
|
446
|
+
|
|
447
|
+
@staticmethod
|
|
448
|
+
def _validate_pagination(limit: int, offset: int) -> None:
|
|
449
|
+
if limit < 1:
|
|
450
|
+
raise ValueError("limit must be greater than 0")
|
|
451
|
+
if offset < 0:
|
|
452
|
+
raise ValueError("offset must be greater than or equal to 0")
|
|
453
|
+
|
|
454
|
+
@staticmethod
|
|
455
|
+
def _to_exception(response: httpx.Response) -> RemembrError:
|
|
456
|
+
status_code = response.status_code
|
|
457
|
+
message = f"Remembr API request failed with status code {status_code}."
|
|
458
|
+
code: str | None = None
|
|
459
|
+
details: dict[str, Any] | None = None
|
|
460
|
+
request_id: str | None = None
|
|
461
|
+
|
|
462
|
+
try:
|
|
463
|
+
payload = response.json()
|
|
464
|
+
if isinstance(payload, dict):
|
|
465
|
+
error = payload.get("error")
|
|
466
|
+
if isinstance(error, dict):
|
|
467
|
+
message = str(error.get("message", message))
|
|
468
|
+
code = error.get("code") if isinstance(error.get("code"), str) else None
|
|
469
|
+
details = error.get("details") if isinstance(error.get("details"), dict) else None
|
|
470
|
+
request_id = (
|
|
471
|
+
error.get("request_id") if isinstance(error.get("request_id"), str) else None
|
|
472
|
+
)
|
|
473
|
+
except ValueError:
|
|
474
|
+
pass
|
|
475
|
+
|
|
476
|
+
if status_code in (401, 403):
|
|
477
|
+
return AuthenticationError(
|
|
478
|
+
message, status_code=status_code, code=code, details=details, request_id=request_id
|
|
479
|
+
)
|
|
480
|
+
if status_code == 404:
|
|
481
|
+
return NotFoundError(
|
|
482
|
+
message, status_code=status_code, code=code, details=details, request_id=request_id
|
|
483
|
+
)
|
|
484
|
+
if status_code == 429:
|
|
485
|
+
return RateLimitError(
|
|
486
|
+
message, status_code=status_code, code=code, details=details, request_id=request_id
|
|
487
|
+
)
|
|
488
|
+
if 500 <= status_code <= 599:
|
|
489
|
+
return ServerError(
|
|
490
|
+
message, status_code=status_code, code=code, details=details, request_id=request_id
|
|
491
|
+
)
|
|
492
|
+
|
|
493
|
+
return RemembrError(
|
|
494
|
+
message, status_code=status_code, code=code, details=details, request_id=request_id
|
|
495
|
+
)
|
remembr/exceptions.py
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""SDK-specific exceptions for Remembr API errors."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class RemembrError(Exception):
|
|
9
|
+
"""Base SDK exception.
|
|
10
|
+
|
|
11
|
+
Attributes:
|
|
12
|
+
message: Human-readable error message.
|
|
13
|
+
status_code: HTTP status code when available.
|
|
14
|
+
code: API error code when available.
|
|
15
|
+
details: Additional API-provided metadata.
|
|
16
|
+
request_id: Request identifier for support/debugging.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
def __init__(
|
|
20
|
+
self,
|
|
21
|
+
message: str,
|
|
22
|
+
*,
|
|
23
|
+
status_code: int | None = None,
|
|
24
|
+
code: str | None = None,
|
|
25
|
+
details: dict[str, Any] | None = None,
|
|
26
|
+
request_id: str | None = None,
|
|
27
|
+
) -> None:
|
|
28
|
+
super().__init__(message)
|
|
29
|
+
self.message = message
|
|
30
|
+
self.status_code = status_code
|
|
31
|
+
self.code = code
|
|
32
|
+
self.details = details
|
|
33
|
+
self.request_id = request_id
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class AuthenticationError(RemembrError):
|
|
37
|
+
"""Raised for authentication/authorization failures."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class NotFoundError(RemembrError):
|
|
41
|
+
"""Raised when requested resource is not found."""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class RateLimitError(RemembrError):
|
|
45
|
+
"""Raised when the API rate limit is exceeded."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class ServerError(RemembrError):
|
|
49
|
+
"""Raised for server-side or transient infrastructure failures."""
|
remembr/models.py
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Pydantic models used by the Remembr Python SDK."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from datetime import datetime
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from pydantic import BaseModel, Field
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class Session(BaseModel):
|
|
12
|
+
request_id: str
|
|
13
|
+
session_id: str
|
|
14
|
+
org_id: str
|
|
15
|
+
created_at: datetime
|
|
16
|
+
metadata: dict[str, Any] | None = None
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class Episode(BaseModel):
|
|
20
|
+
episode_id: str
|
|
21
|
+
session_id: str | None = None
|
|
22
|
+
role: str
|
|
23
|
+
content: str
|
|
24
|
+
created_at: datetime
|
|
25
|
+
tags: list[str] = Field(default_factory=list)
|
|
26
|
+
metadata: dict[str, Any] | None = None
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class SearchResult(BaseModel):
|
|
30
|
+
episode_id: str
|
|
31
|
+
content: str
|
|
32
|
+
role: str
|
|
33
|
+
score: float
|
|
34
|
+
created_at: datetime
|
|
35
|
+
tags: list[str] = Field(default_factory=list)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class MemoryQueryResult(BaseModel):
|
|
39
|
+
request_id: str
|
|
40
|
+
results: list[SearchResult]
|
|
41
|
+
total: int
|
|
42
|
+
query_time_ms: int
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class CheckpointInfo(BaseModel):
|
|
46
|
+
checkpoint_id: str
|
|
47
|
+
created_at: datetime
|
|
48
|
+
message_count: int
|
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: remembr
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Persistent memory infrastructure for AI agents
|
|
5
|
+
Author-email: Emmanuel Nwanguma <nwangumaemmanuel29@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/emartai/remembr
|
|
8
|
+
Project-URL: Repository, https://github.com/emartai/remembr
|
|
9
|
+
Project-URL: Documentation, https://github.com/emartai/remembr#readme
|
|
10
|
+
Project-URL: Bug Tracker, https://github.com/emartai/remembr/issues
|
|
11
|
+
Keywords: ai,memory,agents,llm,langchain,embeddings,vector-search
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: httpx>=0.25.0
|
|
25
|
+
Requires-Dist: pydantic>=2.5.0
|
|
26
|
+
Requires-Dist: tenacity>=8.2.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=7.4.0; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
30
|
+
Requires-Dist: ruff>=0.3.0; extra == "dev"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<div align="center">
|
|
34
|
+
|
|
35
|
+
<img src="./docs/images/logo.png" alt="Remembr Logo" width="400"/>
|
|
36
|
+
|
|
37
|
+
# Remembr
|
|
38
|
+
|
|
39
|
+
**Persistent Memory Infrastructure for AI Agents**
|
|
40
|
+
|
|
41
|
+
[](https://opensource.org/licenses/MIT)
|
|
42
|
+
[](https://www.python.org/downloads/)
|
|
43
|
+
[](https://www.typescriptlang.org/)
|
|
44
|
+
|
|
45
|
+
[Quick Start](#quick-start) • [Framework Adapters](#framework-adapters) • [Self-Hosting](#self-hosting) • [Architecture](#architecture) • [Contributing](#contributing)
|
|
46
|
+
|
|
47
|
+
</div>
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## What is Remembr?
|
|
52
|
+
|
|
53
|
+
Remembr gives AI agents persistent, searchable memory across sessions. Store, search, and retrieve conversation history using semantic search powered by vector embeddings. It supports multi-tenant isolation out of the box, so each user, agent, and session stays scoped and secure. Self-host in minutes with Docker or deploy to any cloud.
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Why Remembr?
|
|
58
|
+
|
|
59
|
+
- **Stateless agents forget everything** — Remembr gives them long-term memory that persists across restarts and deployments
|
|
60
|
+
- **Lost context kills user experience** — agents recall past interactions so users never repeat themselves
|
|
61
|
+
- **No cross-session memory** — Remembr links memory across sessions so agents build a complete picture over time
|
|
62
|
+
- **No multi-tenant isolation** — built-in org → team → user → agent → session scoping keeps data secure and separated
|
|
63
|
+
- **No GDPR compliance** — targeted deletion APIs let you erase user data on demand for right-to-erasure compliance
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Quick Start
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# 1. Clone
|
|
71
|
+
git clone https://github.com/emartai/remembr.git
|
|
72
|
+
cd remembr
|
|
73
|
+
|
|
74
|
+
# 2. Configure environment
|
|
75
|
+
cp .env.example .env
|
|
76
|
+
# Edit .env — set JINA_API_KEY and generate SECRET_KEY:
|
|
77
|
+
# python -c "import secrets; print(secrets.token_hex(32))"
|
|
78
|
+
|
|
79
|
+
# 3. Start services
|
|
80
|
+
docker-compose up -d
|
|
81
|
+
|
|
82
|
+
# 4. Run migrations
|
|
83
|
+
docker-compose exec server alembic upgrade head
|
|
84
|
+
|
|
85
|
+
# 5. Verify
|
|
86
|
+
curl http://localhost:8000/health
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
See [QUICKSTART.md](QUICKSTART.md) for the full walkthrough including user registration and API key setup.
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Install the SDK
|
|
94
|
+
|
|
95
|
+
**Python:**
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pip install remembr
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**TypeScript:**
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
npm install @remembr/sdk
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Python Example
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import asyncio
|
|
111
|
+
from remembr import RemembrClient
|
|
112
|
+
|
|
113
|
+
async def main():
|
|
114
|
+
client = RemembrClient(
|
|
115
|
+
api_key="your-api-key",
|
|
116
|
+
base_url="http://localhost:8000/api/v1"
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
# Create a session
|
|
120
|
+
session = await client.create_session(
|
|
121
|
+
metadata={"user": "demo", "context": "support"}
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
# Store a memory
|
|
125
|
+
await client.store(
|
|
126
|
+
content="User prefers email notifications on Fridays",
|
|
127
|
+
role="user",
|
|
128
|
+
session_id=session.session_id,
|
|
129
|
+
tags=["preference", "notification"]
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
# Search memories
|
|
133
|
+
results = await client.search(
|
|
134
|
+
query="When should I send notifications?",
|
|
135
|
+
session_id=session.session_id,
|
|
136
|
+
limit=5,
|
|
137
|
+
mode="hybrid"
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
for memory in results.results:
|
|
141
|
+
print(f"[{memory.role}] {memory.content} (score: {memory.score:.3f})")
|
|
142
|
+
|
|
143
|
+
await client.aclose()
|
|
144
|
+
|
|
145
|
+
asyncio.run(main())
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### TypeScript Example
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
import { RemembrClient } from '@remembr/sdk';
|
|
152
|
+
|
|
153
|
+
async function main() {
|
|
154
|
+
const client = new RemembrClient({
|
|
155
|
+
apiKey: process.env.REMEMBR_API_KEY!,
|
|
156
|
+
baseUrl: 'http://localhost:8000/api/v1'
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
// Create session
|
|
160
|
+
const session = await client.createSession({
|
|
161
|
+
metadata: { user: 'demo', context: 'support' }
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
// Store memory
|
|
165
|
+
await client.store({
|
|
166
|
+
content: 'User prefers dark mode interface',
|
|
167
|
+
role: 'user',
|
|
168
|
+
sessionId: session.session_id,
|
|
169
|
+
tags: ['preference', 'ui']
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
// Search memories
|
|
173
|
+
const results = await client.search({
|
|
174
|
+
query: 'What are the user UI preferences?',
|
|
175
|
+
sessionId: session.session_id,
|
|
176
|
+
limit: 5,
|
|
177
|
+
mode: 'hybrid'
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
results.results.forEach(memory => {
|
|
181
|
+
console.log(`[${memory.role}] ${memory.content} (score: ${memory.score})`);
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
main();
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Framework Adapters
|
|
191
|
+
|
|
192
|
+
Remembr provides native adapters for 8 major AI frameworks. All adapters are **production-ready** and **fully tested**.
|
|
193
|
+
|
|
194
|
+
| Framework | Adapter | Status |
|
|
195
|
+
|-----------|---------|--------|
|
|
196
|
+
| **LangChain** | `adapters.langchain` | ✅ Tested |
|
|
197
|
+
| **LangGraph** | `adapters.langgraph` | ✅ Tested |
|
|
198
|
+
| **CrewAI** | `adapters.crewai` | ✅ Tested |
|
|
199
|
+
| **AutoGen** | `adapters.autogen` | ✅ Tested |
|
|
200
|
+
| **LlamaIndex** | `adapters.llamaindex` | ✅ Tested |
|
|
201
|
+
| **Pydantic AI** | `adapters.pydantic_ai` | ✅ Tested |
|
|
202
|
+
| **OpenAI Agents** | `adapters.openai_agents` | ✅ Tested |
|
|
203
|
+
| **Haystack** | `adapters.haystack` | ✅ Tested |
|
|
204
|
+
|
|
205
|
+
📚 **[View all adapter guides →](docs/adapters/)**
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## Self-Hosting
|
|
210
|
+
|
|
211
|
+
### Option 1: Docker Compose (Recommended)
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
git clone https://github.com/emartai/remembr.git
|
|
215
|
+
cd remembr
|
|
216
|
+
cp .env.example .env
|
|
217
|
+
# Edit .env with your JINA_API_KEY and SECRET_KEY
|
|
218
|
+
docker-compose up -d
|
|
219
|
+
docker-compose exec server alembic upgrade head
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Option 2: Manual Setup
|
|
223
|
+
|
|
224
|
+
1. Install PostgreSQL 15+ with [pgvector](https://github.com/pgvector/pgvector)
|
|
225
|
+
2. Install Redis 7+
|
|
226
|
+
3. Clone the repo and install Python dependencies:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
python -m venv .venv
|
|
230
|
+
source .venv/bin/activate # or .venv\Scripts\activate on Windows
|
|
231
|
+
pip install -r server/requirements.txt
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
4. Configure `.env` with your database, Redis, and Jina credentials
|
|
235
|
+
5. Run migrations and start the server:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
cd server
|
|
239
|
+
alembic upgrade head
|
|
240
|
+
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
📖 **[Full self-hosting guide →](QUICKSTART.md)**
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Environment Variables
|
|
248
|
+
|
|
249
|
+
| Variable | Description | Required | Default |
|
|
250
|
+
|----------|-------------|----------|---------|
|
|
251
|
+
| `DATABASE_URL` | PostgreSQL connection string (asyncpg) | ✅ | `postgresql+asyncpg://remembr:remembr@localhost:5432/remembr` |
|
|
252
|
+
| `REDIS_URL` | Redis connection string | ✅ | `redis://localhost:6379` |
|
|
253
|
+
| `JINA_API_KEY` | Jina AI API key for embeddings | ✅ | — |
|
|
254
|
+
| `SECRET_KEY` | JWT signing secret (hex string) | ✅ | — |
|
|
255
|
+
| `ENVIRONMENT` | Runtime environment | No | `development` |
|
|
256
|
+
| `LOG_LEVEL` | Logging level | No | `INFO` |
|
|
257
|
+
| `ALGORITHM` | JWT algorithm | No | `HS256` |
|
|
258
|
+
| `ACCESS_TOKEN_EXPIRE_MINUTES` | JWT access token lifetime | No | `30` |
|
|
259
|
+
| `REFRESH_TOKEN_EXPIRE_DAYS` | JWT refresh token lifetime | No | `7` |
|
|
260
|
+
| `JINA_EMBEDDING_MODEL` | Jina embedding model name | No | `jina-embeddings-v3` |
|
|
261
|
+
| `EMBEDDING_BATCH_SIZE` | Batch size for embedding requests | No | `100` |
|
|
262
|
+
| `DB_POOL_SIZE` | Database connection pool size | No | `10` |
|
|
263
|
+
| `DB_MAX_OVERFLOW` | Max overflow connections | No | `20` |
|
|
264
|
+
| `DB_POOL_TIMEOUT` | Pool connection timeout (seconds) | No | `30` |
|
|
265
|
+
| `DB_POOL_RECYCLE` | Connection recycle interval (seconds) | No | `1800` |
|
|
266
|
+
| `RATE_LIMIT_DEFAULT_PER_MINUTE` | Default rate limit | No | `100` |
|
|
267
|
+
| `RATE_LIMIT_SEARCH_PER_MINUTE` | Search rate limit | No | `30` |
|
|
268
|
+
| `SHORT_TERM_MAX_TOKENS` | Max tokens in short-term window | No | `4000` |
|
|
269
|
+
| `SHORT_TERM_AUTO_CHECKPOINT_THRESHOLD` | Auto-checkpoint threshold | No | `0.8` |
|
|
270
|
+
| `API_V1_PREFIX` | API version prefix | No | `/api/v1` |
|
|
271
|
+
| `CORS_ORIGINS` | Allowed CORS origins (JSON array) | No | `[]` |
|
|
272
|
+
| `SENTRY_DSN` | Sentry error tracking DSN | No | — |
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## Architecture
|
|
277
|
+
|
|
278
|
+
```mermaid
|
|
279
|
+
graph TB
|
|
280
|
+
subgraph "AI Frameworks"
|
|
281
|
+
LC[LangChain]
|
|
282
|
+
LG[LangGraph]
|
|
283
|
+
CA[CrewAI]
|
|
284
|
+
AG[AutoGen]
|
|
285
|
+
LI[LlamaIndex]
|
|
286
|
+
PA[Pydantic AI]
|
|
287
|
+
OA[OpenAI Agents]
|
|
288
|
+
HS[Haystack]
|
|
289
|
+
end
|
|
290
|
+
|
|
291
|
+
subgraph "Remembr Platform"
|
|
292
|
+
subgraph "SDK Layer"
|
|
293
|
+
PY[Python SDK]
|
|
294
|
+
TS[TypeScript SDK]
|
|
295
|
+
end
|
|
296
|
+
|
|
297
|
+
subgraph "API Server — FastAPI"
|
|
298
|
+
AUTH[Authentication]
|
|
299
|
+
MEM[Memory API]
|
|
300
|
+
SESS[Sessions API]
|
|
301
|
+
RATE[Rate Limiting]
|
|
302
|
+
end
|
|
303
|
+
|
|
304
|
+
subgraph "Storage"
|
|
305
|
+
PG["PostgreSQL + pgvector
|
|
306
|
+
Long-term episodic memory"]
|
|
307
|
+
REDIS["Redis
|
|
308
|
+
Short-term cache"]
|
|
309
|
+
end
|
|
310
|
+
|
|
311
|
+
JINA["Jina AI
|
|
312
|
+
Embeddings"]
|
|
313
|
+
end
|
|
314
|
+
|
|
315
|
+
LC --> PY
|
|
316
|
+
LG --> PY
|
|
317
|
+
CA --> PY
|
|
318
|
+
AG --> PY
|
|
319
|
+
LI --> PY
|
|
320
|
+
PA --> PY
|
|
321
|
+
OA --> PY
|
|
322
|
+
HS --> PY
|
|
323
|
+
|
|
324
|
+
PY --> AUTH
|
|
325
|
+
TS --> AUTH
|
|
326
|
+
AUTH --> MEM
|
|
327
|
+
AUTH --> SESS
|
|
328
|
+
AUTH --> RATE
|
|
329
|
+
MEM --> PG
|
|
330
|
+
MEM --> REDIS
|
|
331
|
+
MEM --> JINA
|
|
332
|
+
SESS --> REDIS
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Remembr is built on a **FastAPI** server backed by **PostgreSQL with pgvector** for long-term episodic memory storage and semantic vector search, **Redis** for short-term conversation window caching and rate limiting, and **Jina AI** for generating high-quality text embeddings. The system uses multi-tenant row-level security (RLS) to isolate data across organizations, teams, users, agents, and sessions. Authentication is handled via JWT tokens with refresh support, and the entire stack can be self-hosted with Docker Compose or deployed to any cloud platform.
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## Repository Structure
|
|
340
|
+
|
|
341
|
+
```
|
|
342
|
+
remembr/
|
|
343
|
+
├── adapters/ # Framework adapters (8 frameworks)
|
|
344
|
+
│ ├── langchain/
|
|
345
|
+
│ ├── langgraph/
|
|
346
|
+
│ ├── crewai/
|
|
347
|
+
│ ├── autogen/
|
|
348
|
+
│ ├── llamaindex/
|
|
349
|
+
│ ├── pydantic_ai/
|
|
350
|
+
│ ├── openai_agents/
|
|
351
|
+
│ └── haystack/
|
|
352
|
+
├── server/ # FastAPI server
|
|
353
|
+
│ ├── app/ # Application code
|
|
354
|
+
│ │ ├── api/ # REST endpoints
|
|
355
|
+
│ │ ├── db/ # Database models & connection
|
|
356
|
+
│ │ ├── services/ # Business logic
|
|
357
|
+
│ │ ├── repositories/ # Data access layer
|
|
358
|
+
│ │ └── middleware/ # Auth, rate limiting
|
|
359
|
+
│ ├── alembic/ # Database migrations
|
|
360
|
+
│ └── tests/ # Server unit & integration tests
|
|
361
|
+
├── sdk/ # Client SDKs
|
|
362
|
+
│ ├── python/ # Python SDK (PyPI: remembr)
|
|
363
|
+
│ └── typescript/ # TypeScript SDK (npm: @remembr/sdk)
|
|
364
|
+
├── docs/ # Documentation
|
|
365
|
+
│ ├── adapters/ # Adapter-specific guides
|
|
366
|
+
│ ├── api-reference.md # REST API reference
|
|
367
|
+
│ └── images/ # Logo and diagrams
|
|
368
|
+
├── tests/ # End-to-end & integration tests
|
|
369
|
+
├── docker-compose.yml # Local development stack
|
|
370
|
+
├── .env.example # Environment template
|
|
371
|
+
├── QUICKSTART.md # Self-hosted setup guide
|
|
372
|
+
├── CONTRIBUTING.md # Contribution guidelines
|
|
373
|
+
└── LICENSE # MIT License
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## Contributing
|
|
379
|
+
|
|
380
|
+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
|
|
381
|
+
|
|
382
|
+
- Development environment setup
|
|
383
|
+
- Branching strategy and commit conventions
|
|
384
|
+
- Testing guidelines
|
|
385
|
+
- Pull request process
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## License
|
|
390
|
+
|
|
391
|
+
MIT License — Copyright (c) 2026 [Emmanuel Nwanguma](https://linkedin.com/in/nwangumaemmanuel)
|
|
392
|
+
|
|
393
|
+
See [LICENSE](LICENSE) for full text.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
remembr/__init__.py,sha256=MNdaVo9MPJOZddRqzLQP2RHzXeMedBNYsVAMDY3GuBc,525
|
|
2
|
+
remembr/client.py,sha256=5AaPhYfsGQ_BoC6kw4losbl8quDotrq8KqT-ONvqdEw,19646
|
|
3
|
+
remembr/exceptions.py,sha256=cMDWY-Ijj38yQfsz3fez8zcVUWrwzUq7TlJYC1GSIl8,1337
|
|
4
|
+
remembr/models.py,sha256=Mw5U978PVuqCyJuHQqnAW5KjMoHXc3w_StFAVyyHEHo,1024
|
|
5
|
+
remembr-0.1.0.dist-info/licenses/LICENSE,sha256=A7ijgYwQR8rNjOa5eZ1BIW_sTT6QFCnTuZaPneCrpXk,1095
|
|
6
|
+
remembr-0.1.0.dist-info/METADATA,sha256=yBZAI481JsCglVGVOtQQd1VhpAqNTdj70HRfqlZYf6Q,12637
|
|
7
|
+
remembr-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
|
|
8
|
+
remembr-0.1.0.dist-info/top_level.txt,sha256=_yt79fTcOWW_RukNUR4qsdowlC76w20Dm8_bgQD8j3w,8
|
|
9
|
+
remembr-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Emmanuel Nwanguma
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
remembr
|