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 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
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
42
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
43
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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