remembr 0.1.0__tar.gz

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-0.1.0/LICENSE ADDED
@@ -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.
remembr-0.1.0/PKG-INFO ADDED
@@ -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.