telemem 1.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.
telemem-1.1.0/PKG-INFO ADDED
@@ -0,0 +1,636 @@
1
+ Metadata-Version: 2.4
2
+ Name: telemem
3
+ Version: 1.1.0
4
+ Summary: High-performance drop-in replacement of Mem0
5
+ License: Apache-2.0
6
+ Project-URL: Homepage, https://github.com/TeleAI-UAGI/telemem
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: openai
10
+ Requires-Dist: pydantic
11
+ Requires-Dist: chromadb
12
+ Requires-Dist: opencv-python-headless
13
+ Requires-Dist: nano-vectordb
14
+ Requires-Dist: mem0ai
15
+ Requires-Dist: tqdm
16
+ Requires-Dist: azure-identity
17
+ Requires-Dist: yt_dlp
18
+ Requires-Dist: faiss-cpu
19
+
20
+ <p align="center">
21
+ <a href="https://github.com/TeleAI-UAGI/telemem">
22
+ <img src="./assets/TeleMem.png" width="40%" />
23
+ </a>
24
+ </p>
25
+
26
+ <h1 align="center"> TeleMem: Building Long-Term and Multimodal Memory for Agentic AI </h1>
27
+
28
+ <p align="center">
29
+ <a href="docs/TeleMem_Tech_Report.pdf">
30
+ <img src="https://img.shields.io/badge/arXiv-Paper-red" alt="arXiv">
31
+ </a>
32
+ <a href="https://github.com/TeleAI-UAGI/telemem">
33
+ <img src="https://img.shields.io/github/stars/TeleAI-UAGI/TeleMem?style=social" alt="GitHub Stars">
34
+ </a>
35
+ <a href="https://github.com/TeleAI-UAGI/TeleMem/blob/main/LICENSE">
36
+ <img src="https://img.shields.io/badge/license-Apache%20License%202.0-blue" alt="License: Apache 2.0">
37
+ </a>
38
+ <img src="https://img.shields.io/github/last-commit/TeleAI-UAGI/TeleMem?color=blue" alt="Last Commit">
39
+ <img src="https://img.shields.io/badge/PRs-Welcome-red" alt="PRs Welcome">
40
+ </p>
41
+
42
+ <div align="center">
43
+
44
+ **If you find this project helpful, please give us a ⭐️ on GitHub for the latest update.**
45
+
46
+ </div>
47
+
48
+ ---
49
+
50
+
51
+ <div align="center">
52
+ <p>
53
+ <a href="README.md">English</a> | <a href="docs/README-ZH.md">简体中文</a>
54
+ </p>
55
+ <p>
56
+ <a href="https://github.com/TeleAI-UAGI/Awesome-Agent-Memory"> <strong>📄 Awesome-Agent-Memory →</strong></a>
57
+ </p>
58
+ </div>
59
+
60
+ TeleMem is an agent memory management layer that can be used as <mark>**a drop-in replacement for [Mem0](https://mem0.ai/)** with one line of code (`import vendor.TeleMem as mem0`)</mark>, deeply optimized for complex scenarios involving **multi-turn dialogues**, **character modeling**, **long-term information storage**, and **semantic retrieval**.
61
+
62
+ Through its unique **context-aware enhancement mechanism**, TeleMem provides conversational AI with core infrastructure offering **higher accuracy**, **faster performance**, and **stronger character memory capabilities**.
63
+
64
+ Building upon this foundation, TeleMem implements **video understanding, multimodal reasoning, and visual question answering** capabilities. Through a complete pipeline of video frame extraction, caption generation, and vector database construction, AI Agents can effortlessly **store, retrieve, and reason over video content** just like handling text memories.
65
+
66
+ The ultimate goal of the TeleMem project is to _use an agent's hindsight to improve its foresignt_.
67
+
68
+ **TeleMem, where memory lives on and intelligence grows strong.**
69
+
70
+ ---
71
+
72
+ ## 📢 Latest Updates
73
+
74
+ - **[2025-12-31] 🎉 TeleMem [v1.1.0](https://github.com/TeleAI-UAGI/telemem/releases/tag/v1.1.0) Released!**
75
+ - **[2025-12-05] 🎉 TeleMem [v1.0.0](https://github.com/TeleAI-UAGI/telemem/releases/tag/v1.0.0) Released!**
76
+
77
+ ---
78
+
79
+ ## 🔥 Research Highlights
80
+
81
+ * **Significantly improved memory accuracy**: Achieved **86.33%** accuracy on the ZH-4O Chinese multi-character long-dialogue benchmark, **19% higher** than Mem0.
82
+ * **Doubled speed performance**: Millisecond-level semantic retrieval enabled by efficient buffering and batch writing.
83
+ * **Greatly reduced token cost**: Optimized token usage delivers the same performance with significantly lower LLM overhead.
84
+ * **Precise character memory preservation**: Automatically builds independent memory profiles for each character, eliminating confusion.
85
+ * **Automated Video Processing Pipeline**: From raw video → frame extraction → caption generation → vector database, fully automated
86
+ * **ReAct-Style Video QA**: Multi-step reasoning + tool calling for precise video content understanding
87
+
88
+ ---
89
+
90
+ ## 📌 Table of Contents
91
+
92
+ * [Project Introduction](#project-introduction)
93
+ * [TeleMem vs Mem0: Core Advantages](#telemem-vs-mem0-core-advantages)
94
+ * [Experimental Results](#experimental-results)
95
+ * [Quick Start](#quick-start)
96
+ * [Project Structure](#project-structure)
97
+ * [Core Functions](#core-functions)
98
+ * [Multimodal Extensions](#multimodal-extensions)
99
+ * [Data Storage Explanation](#data-storage)
100
+ * [Development and Contribution](#development-and-contribution)
101
+ * [Acknowledgements](#acknowledgements)
102
+
103
+ ---
104
+
105
+ ## Project Introduction
106
+
107
+ TeleMem enables conversational AI to maintain stable, natural, and continuous worldviews and character settings during long-term interactions through a deeply optimized pipeline of **character-aware summarization → semantic clustering deduplication → efficient storage → precise retrieval**.
108
+
109
+ ### Features
110
+
111
+ - **Automatic memory extraction**: Extracts and structures key facts from dialogues.
112
+ - **Semantic clustering & deduplication**: Uses LLMs to semantically merge similar memories, reducing conflicts and improving consistency.
113
+ - **Character-profiled memory management**: Builds independent memory archives for each character in a dialogue, ensuring precise isolation and personalized management.
114
+ - **Efficient asynchronous writing**: Employs a buffer + batch-flush mechanism for high-performance, stable persistence.
115
+ - **Precise semantic retrieval**: Combines **FAISS + JSON dual storage** for fast recall and human-readable auditability.
116
+
117
+ ### Applicable Scenarios
118
+
119
+ * Multi-character virtual agent systems
120
+ * Long-memory AI assistants (e.g., customer service, companionship, creative co-pilots)
121
+ * Complex narrative/world-building in virtual environments
122
+ * Dialogue scenarios with strong contextual dependencies
123
+ * Video content QA and reasoning
124
+ * Multimodal agent memory management
125
+ * Long video understanding and information retrieval
126
+
127
+ ![image](assets/text-writing.png)
128
+
129
+ ---
130
+
131
+ ## TeleMem vs Mem0: Core Advantages
132
+
133
+ TeleMem deeply refactors Mem0 to address **characterization**, **long-term memory**, and **high performance**. Key differences:
134
+
135
+ | Capability Dimension | Mem0 | TeleMem |
136
+ | -------------------------- | --------------------------- | ------------------------------------------------------------ |
137
+ | Multi-character separation | ❌ Not supported | ✅ Automatically creates **independent memory profiles** per character |
138
+ | Summary quality | Basic summarization | ✅ **Context-aware + character-focused prompts** covering key entities, actions, and timestamps |
139
+ | Deduplication mechanism | Vector similarity filtering | ✅ **LLM-based semantic clustering**: merges similar memories via LLM |
140
+ | Write performance | Streaming, single writes | ✅ **Batch flush + concurrency**: 2–3× faster writes |
141
+ | Storage format | SQLite / vector DB | ✅ **FAISS + JSON metadata dual-write**: fast retrieval + human-readable |
142
+ | Multimodal Capability | Single image to text only | ✅ **Video Multimodal Memory**: Full video processing pipeline + ReAct multi-step reasoning QA |
143
+ ---
144
+
145
+ ## Experimental Results
146
+
147
+ ### Dataset
148
+
149
+ We evaluate the ZH-4O Chinese long-character dialogue dataset constructed in the paper [MOOM: Maintenance, Organization and Optimization of Memory in Ultra-Long Role-Playing Dialogues](https://arxiv.org/abs/2509.11860):
150
+
151
+ - Average dialogue length: **600 turns per conversation**
152
+ - Scenarios: daily interactions, plot progression, evolving character relationships
153
+
154
+ Memory capability was assessed via QA benchmarks, e.g.:
155
+
156
+ ```json
157
+ {
158
+ "question": "What is Zhao Qi's nickname for Bai Yulan? A Xiaobai B Xiaoyu C Lanlan D Yuyu",
159
+ "answer": "A"
160
+ },
161
+ {
162
+ "question": "What is the relationship between Zhao Qi and Bai Yulan? A Classmates B Teacher and student C Enemies D Neighbors",
163
+ "answer": "B"
164
+ }
165
+ ```
166
+
167
+ ### Experimental Configuration
168
+
169
+ - LLM: [Qwen3-8B](https://huggingface.co/Qwen/Qwen3-8B) (thinking mode disabled)
170
+ - Embedding model: [Qwen3-Embedding-8B](https://huggingface.co/Qwen/Qwen3-Embedding-8B)
171
+ - Metric: QA accuracy
172
+
173
+ | Method | Overall(%) |
174
+ |:--------------------------------------------------------- |:---------- |
175
+ | RAG | 62.45 |
176
+ | _[Mem0](https://github.com/mem0ai/mem0)_ | _70.20_ |
177
+ | [MOOM](https://github.com/cows21/MOOM-Roleplay-Dialogue) | 72.60 |
178
+ | [A-mem](https://github.com/agiresearch/A-mem) | 73.78 |
179
+ | [Memobase](https://github.com/memodb-io/memobase) | 76.78 |
180
+ | **[TeleMem](https://github.com/TeleAI-UAGI/TeleMem)** | **86.33** |
181
+
182
+ <!--
183
+ | Long-Context LLM (Slow and Expensive) | 84.92 |
184
+ -->
185
+
186
+ ---
187
+
188
+ ## Quick Start
189
+
190
+ ### Environment Preparation
191
+
192
+ ```shell
193
+ # Create and activate virtual environment
194
+ conda create -n telemem python=3.10
195
+ conda activate telemem
196
+ # Install dependencies
197
+ pip install -r requirements.txt
198
+ ```
199
+
200
+ ### Apply Patches
201
+
202
+ ```shell
203
+ # Run patch application script (see TeleMem-Overlay.md for details)
204
+ bash scripts/apply_patches.sh
205
+ ```
206
+
207
+ ### Example
208
+
209
+ Set your OpenAI API key:
210
+ ```shell
211
+ export OPENAI_API_KEY="your-openai-api-key"
212
+ ```
213
+
214
+ ```python
215
+ # python examples/quickstart.py
216
+ import vendor.TeleMem as mem0
217
+
218
+ memory = mem0.Memory()
219
+
220
+ messages = [
221
+ {"role": "user", "content": "Jordan, did you take the subway to work again today?"},
222
+ {"role": "assistant", "content": "Yes, James. The subway is much faster than driving. I leave at 7 o'clock and it's just not crowded."},
223
+ {"role": "user", "content": "Jordan, I want to try taking the subway too. Can you tell me which station is closest?"},
224
+ {"role": "assistant", "content": "Of course, James. You take Line 2 to Civic Center Station, exit from Exit A, and walk 5 minutes to the company."}
225
+ ]
226
+
227
+ memory.add(messages=messages, user_id="Jordan")
228
+ results = memory.search("What transportation did Jordan use to go to work today?", user_id="Jordan")
229
+ print(results)
230
+ ```
231
+
232
+ By default `Memory()` wires up:
233
+ - OpenAI gpt-4.1-nano-2025-04-14 for summary extraction and updates
234
+ - OpenAI text-embedding-3-small embeddings (1536 dimensions)
235
+ - Faiss vector store with on-disk data
236
+
237
+ If you want to customize the configuration, please modify `config/config.yaml`.
238
+
239
+ ---
240
+
241
+ ## Project Structure
242
+
243
+ <details>
244
+ <summary>Expand/Collapse Directory Structure</summary>
245
+
246
+ ```
247
+ telemem/
248
+ ├── assets/ # Documentation assets and figures
249
+ ├── vendor/
250
+ │ └── mem0/                 # Upstream repository source code
251
+ ├── overlay/
252
+ │ └── patches/              # TeleMem custom patch files (.patch)
253
+ ├── scripts/                # Overlay management scripts
254
+ │ ├── init_upstream.sh      # Initialize upstream subtree
255
+ │ ├── update_upstream.sh    # Sync upstream and reapply patches
256
+ │ ├── record_patch.sh       # Record local modifications as patches
257
+ │ └── apply_patches.sh      # Apply patches
258
+ ├── baselines/ # Baseline implementations for comparative evaluation
259
+ │ ├── RAG # Retrieval-Augmented Generation baseline
260
+ │ ├── MemoBase # MemoBase memory management system
261
+ │ ├── MOOM # MOOM dual-branch narrative memory framework
262
+ │ ├── A-mem # A-mem agent memory baseline
263
+ │ └── Mem0 # Mem0 baseline implementation
264
+ ├── config/
265
+ | └── config.yaml # TeleMem configuration
266
+ ├── data/ # Small sample datasets for evaluation or demonstration
267
+ ├── examples/ # Code examples and tutorial demos
268
+ │ ├── quickstart.py         # Quick start
269
+ │ └── quickstart_mm.py # Quick start(Multimodel)
270
+ ├── docs/
271
+ │ ├── TeleMem-Overlay.md    # Overlay development guide (English)
272
+ │ ├── TeleMem-Overlay-ZH.md # Overlay development guide (Chinese)
273
+ │ └── README-ZH.md          # Chinese README
274
+ ├── PATCHES.md              # Patch list and descriptions
275
+ └── README.md               # This file
276
+ ```
277
+
278
+ </details>
279
+
280
+ ---
281
+
282
+ ## Core Functions
283
+
284
+ ### Add Memory (add)
285
+
286
+ The `add()` method injects one or more dialogue turns into the memory system.
287
+
288
+ ```python
289
+ def add(
290
+ self,
291
+ messages,
292
+ *,
293
+ user_id: Optional[str] = None,
294
+ agent_id: Optional[str] = None,
295
+ run_id: Optional[str] = None,
296
+ metadata: Optional[Dict[str, Any]] = None,
297
+ infer: bool = True,
298
+ memory_type: Optional[str] = None,
299
+ prompt: Optional[str] = None,
300
+ )
301
+ ```
302
+
303
+ #### 🔎 Parameter Description
304
+
305
+ | Parameter | Type | Required | Description |
306
+ | --------------------------------- | ---------------------- | -------- | ------------------------------------------------------------ |
307
+ | `messages` | `List[Dict[str, str]]` | ✅ Yes | List of dialogue messages, each with `role` (`user`/`assistant`) and `content` |
308
+ | `metadata` | `Dict[str, Any]` | ✅ Yes | Must include: <br>・`sample_id`: unique session ID <br>・`user`: list of character names |
309
+ | `user_id` / `agent_id` / `run_id` | Optional[str] | ❌ No | Mem0-compatible parameters (ignored in TeleMem) |
310
+ | `infer` | `bool` | ❌ No | Whether to auto-generate memory summaries (default: `True`) |
311
+ | `memory_type` | Optional[str] | ❌ No | Memory category (auto-classified if omitted) |
312
+ | `prompt` | Optional[str] | ❌ No | Custom prompt for summarization (uses optimized default if omitted) |
313
+
314
+ #### 🔁 Internal Workflow of `add()`
315
+
316
+ 1. **Message preprocessing**: Merge consecutive messages from the same speaker; normalize turn structure.
317
+ 2. **Multi-perspective summarization**:
318
+ - Global event summary
319
+ - Character 1’s perspective (actions, preferences, relationships)
320
+ - Character 2’s perspective
321
+ 3. **Vectorization & similarity search**: Generate embeddings and retrieve existing similar memories.
322
+ 4. **Batch processing**: When buffer threshold is reached, invoke LLM to **semantically merge** similar memories.
323
+ 5. **Persistence**: Dual-write to **FAISS (for retrieval)** and **JSON (for metadata)**.
324
+
325
+ ---
326
+
327
+ ### Search Memory (search)
328
+
329
+ Performs semantic vector-based retrieval of relevant memories with context-aware recall.
330
+
331
+ ```python
332
+ def search(
333
+ self,
334
+ query: str,
335
+ *,
336
+ user_id: Optional[str] = None,
337
+ agent_id: Optional[str] = None,
338
+ run_id: Optional[str] = None,
339
+ limit: int = 5,
340
+ filters: Optional[Dict[str, Any]] = None,
341
+ threshold: Optional[float] = None,
342
+ rerank: bool = True,
343
+ )
344
+ ```
345
+
346
+ #### 🔎 Parameter Description
347
+
348
+ | Parameter | Type | Required | Description |
349
+ | ---------------------- | ---------------- | -------- | ------------------------------------------------- |
350
+ | `query` | `str` | ✅ Yes | Natural language query |
351
+ | `run_id` | `str` | ✅ Yes | Session ID (must match `sample_id` used in `add`) |
352
+ | `limit` | `int` | ❌ No | Max number of results (default: 5) |
353
+ | `threshold` | `float` | ❌ No | Similarity threshold (0–1; auto-tuned if omitted) |
354
+ | `filters` | `Dict[str, Any]` | ❌ No | Custom filters (e.g., by character, time range) |
355
+ | `rerank` | `bool` | ❌ No | Whether to rerank results (default: `True`) |
356
+ | `user_id` / `agent_id` | Optional[str] | ❌ No | Mem0-compatible (no effect in TeleMem) |
357
+
358
+ > 🔍 Search is based on FAISS vector retrieval, supporting millisecond-level responses.
359
+
360
+ ---
361
+
362
+ ## Multimodal Extensions
363
+
364
+ Beyond text memory, TeleMem further extends multimodal capabilities. Drawing inspiration from [Deep Video Discovery](https://github.com/microsoft/DeepVideoDiscovery)'s Agentic Search and Tool Use approach, we implemented two core methods in the TeleMemory class to support intelligent storage and semantic retrieval of video content.
365
+
366
+ | Method | Description |
367
+ |------|----------|
368
+ | `add_mm()` | Process video into retrievable memory (frame extraction → caption generation → vector database) |
369
+ | `search_mm()` | Query video content using natural language, supporting ReAct-style multi-step reasoning |
370
+
371
+ ### Add Multimodal Memory (add_mm)
372
+
373
+ ```python
374
+ def add_mm(
375
+ self,
376
+ video_path: str,
377
+ *,
378
+ frames_root: str = "video/frames",
379
+ captions_root: str = "video/captions",
380
+ vdb_root: str = "video/vdb",
381
+ clip_secs: int = None,
382
+ emb_dim: int = None,
383
+ subtitle_path: str | None = None,
384
+ )
385
+ ```
386
+
387
+ #### 🔎 Parameter Description
388
+
389
+ | Parameter | Type | Required | Description |
390
+ |--------|------|----------|------|
391
+ | video_path | str | ✅ Yes | Source video file path, e.g., `"video/3EQLFHRHpag.mp4"` |
392
+ | frames_root | str | ❌ No | Frame output root directory (default `"video/frames"`) |
393
+ | captions_root | str | ❌ No | Caption JSON output root directory (default `"video/captions"`) |
394
+ | vdb_root | str | ❌ No | Vector database output root directory (default `"video/vdb"`) |
395
+ | clip_secs | int | ❌ No | Seconds per clip, overrides config.CLIP_SECS |
396
+ | emb_dim | int | ❌ No | Embedding dimension, reads from config by default |
397
+ | subtitle_path | str | ❌ No | Subtitle file path (.srt), optional |
398
+
399
+ #### 🔁 add_mm() Internal Flow
400
+
401
+ 1. **Frame Extraction**: `decode_video_to_frames` - Decodes video to JPEG frames at configured FPS
402
+ 2. **Caption Generation**: `process_video` - Uses VLM (e.g., Qwen3-Omni) to generate detailed descriptions for each clip
403
+ 3. **Vector Database Construction**: `init_single_video_db` - Generates embeddings for semantic retrieval
404
+
405
+ > 💡 **Smart Caching**: If the target file for a stage already exists, that stage is automatically skipped to save computational resources.
406
+
407
+ #### Return Value Example
408
+
409
+ ```python
410
+ {
411
+ "video_name": "3EQLFHRHpag",
412
+ "frames_dir": "video/frames/3EQLFHRHpag/frames",
413
+ "caption_json": "video/captions/3EQLFHRHpag/captions.json",
414
+ "vdb_json": "video/vdb/3EQLFHRHpag/3EQLFHRHpag_vdb.json"
415
+ }
416
+ ```
417
+
418
+ ---
419
+
420
+ ### Search Multimodal Memory (search_mm)
421
+
422
+ ```python
423
+ def search_mm(
424
+ self,
425
+ question: str,
426
+ video_db_path: str = "video/vdb/3EQLFHRHpag_vdb.json",
427
+ video_caption_path: str = "video/captions/captions.json",
428
+ max_iterations: int = 15,
429
+ )
430
+ ```
431
+
432
+ #### 🔎 Parameter Description
433
+
434
+ | Parameter | Type | Required | Description |
435
+ |--------|------|----------|------|
436
+ | question | str | ✅ Yes | Question string (supports A/B/C/D multiple choice format) |
437
+ | video_db_path | str | ❌ No | Video vector database path |
438
+ | video_caption_path | str | ❌ No | Video caption JSON path |
439
+ | max_iterations | int | ❌ No | Maximum MMCoreAgent reasoning iterations (default 15) |
440
+
441
+ #### 🛠️ ReAct-Style Reasoning Tools
442
+
443
+ `search_mm` internally uses `MMCoreAgent`, employing a THINK → ACTION → OBSERVATION loop with three specialized tools:
444
+
445
+ | Tool Name | Function |
446
+ |--------|------|
447
+ | `global_browse_tool` | Get global overview of video events and themes |
448
+ | `clip_search_tool` | Search for specific content using semantic queries |
449
+ | `frame_inspect_tool` | Inspect frame details within a specific time range |
450
+
451
+ ---
452
+
453
+ ### Multimodal Example
454
+
455
+ Run the multimodal demo:
456
+
457
+ ```bash
458
+ python examples/quickstart_mm.py
459
+ ```
460
+
461
+ On the first run, all frames, captions and VDB JSON will be generated under `output_dir` (default `data/samples/video/`). For reproducibility, we also ship these intermediates in the repo so you can run queries directly without recomputing.
462
+
463
+ Complete code example:
464
+
465
+ ```python
466
+ import vendor.TeleMem as mem0
467
+ import os
468
+
469
+ # Initialize
470
+ memory = mem0.Memory()
471
+
472
+ # Define paths
473
+ video_path = "data/samples/video/3EQLFHRHpag.mp4"
474
+ video_name = os.path.splitext(os.path.basename(video_path))[0]
475
+ output_dir = "data/samples/video"
476
+ os.makedirs(output_dir, exist_ok=True)
477
+
478
+
479
+ # Step 1: Add video to memory (auto-processing)
480
+ vdb_json_path = f"{output_dir}/vdb/{video_name}/{video_name}_vdb.json"
481
+ if not os.path.exists(vdb_json_path):
482
+ result = memory.add_mm(
483
+ video_path=video_path,
484
+ output_dir=output_dir,
485
+ )
486
+ print(f"Video processing complete: {result}")
487
+ else:
488
+ print(f"VDB already exists: {vdb_json_path}")
489
+
490
+ # Step 2: Query video content
491
+ question = """The problems people encounter in the video are caused by what?
492
+ (A) Catastrophic weather.
493
+ (B) Global warming.
494
+ (C) Financial crisis.
495
+ (D) Oil crisis.
496
+ """
497
+
498
+ messages = memory.search_mm(
499
+ question=question,
500
+ output_dir=output_dir,
501
+ max_iterations=15,
502
+ )
503
+
504
+ # Extract final answer
505
+ from core import extract_choice_from_msg
506
+ answer = extract_choice_from_msg(messages)
507
+ print(f"Answer: ({answer})")
508
+ ```
509
+
510
+ ---
511
+
512
+ ## Data Storage
513
+
514
+ ### Text Memory Storage
515
+
516
+ TeleMem automatically creates a structured storage layout under `./faiss_db/`, organized by session and character:
517
+
518
+ ```
519
+ faiss_db/
520
+ ├── session_001_events.index
521
+ ├── session_001_events_meta.json
522
+ ├── session_001_person_1.index
523
+ ├── session_001_person_1_meta.json
524
+ ├── session_001_person_2.index
525
+ └── session_001_person_2_meta.json
526
+ ```
527
+
528
+ ### 📄 Metadata Example (_meta.json)
529
+
530
+ ```json
531
+ {
532
+ "summary": "Characters discussed the upcoming action plan.",
533
+ "sample_id": "session_001",
534
+ "round_index": 3,
535
+ "timestamp": "2024-01-01T00:00:00Z",
536
+ "user": "Jordan" // Only present in person_*.json
537
+ }
538
+ ```
539
+
540
+ > All memories include summary, round number, timestamp, and character, facilitating auditing and debugging.
541
+
542
+ ------
543
+
544
+ ### Multimodal Memory Storage
545
+
546
+ TeleMem generates video-related storage files in the `.data/samples/video/` directory:
547
+
548
+ ```
549
+ video/
550
+ ├── frames/
551
+ │ └── <video_name>/
552
+ │ └── frames/
553
+ │ ├── frame_000001_n0.00.jpg
554
+ │ ├── frame_000002_n0.50.jpg
555
+ │ └── ...
556
+ ├── captions/
557
+ │ └── <video_name>/
558
+ │ ├── captions.json # Clip descriptions + subject registry
559
+ │ └── ckpt/ # Checkpoint for resume
560
+ │ ├── 0_10.json
561
+ │ └── 10_20.json
562
+ └── vdb/
563
+ └── <video_name>/
564
+ └── <video_name>_vdb.json # Semantic retrieval vector database
565
+ ```
566
+
567
+ #### 📄 captions.json Structure
568
+
569
+ ```json
570
+ {
571
+ "0_10": {
572
+ "caption": "The narrator discusses climate data, showing melting glaciers..."
573
+ },
574
+ "10_20": {
575
+ "caption": "Scene shifts to coastal communities affected by rising sea levels..."
576
+ },
577
+ "subject_registry": {
578
+ "narrator": {
579
+ "name": "narrator",
580
+ "appearance": ["professional attire"],
581
+ "identity": ["climate scientist"],
582
+ "first_seen": "00:00:00"
583
+ }
584
+ }
585
+ }
586
+ ```
587
+
588
+ ------
589
+
590
+ ## Development and Contribution
591
+
592
+ * Overlay development process: [TeleMem-Overlay.md](docs/TeleMem-Overlay.md)
593
+ * Chinese documentation: [README-ZH.md](docs/README-ZH.md)
594
+
595
+ ---
596
+ ## License
597
+
598
+ [Apache 2.0 License](LICENSE)
599
+
600
+ ---
601
+
602
+ ## Acknowledgements
603
+
604
+ TeleMem’s development has been deeply inspired by open-source communities and cutting-edge research. We extend our sincere gratitude to the following projects and teams:
605
+
606
+ - [**Mem0**](https://github.com/mem0ai/mem0)
607
+ - [**Memobase**](https://github.com/memodb-io/memobase)
608
+ - [**MOOM**](https://github.com/cows21/MOOM-Roleplay-Dialogue)
609
+ - [**DVD**](https://github.com/microsoft/DeepVideoDiscovery)
610
+ - [**Memento**](https://github.com/Agent-on-the-Fly/Memento)
611
+
612
+ ------
613
+
614
+ ## Star History
615
+
616
+ [![Star History Chart](https://api.star-history.com/svg?repos=TeleAI-UAGI/telemem&type=date&legend=top-left)](https://www.star-history.com/#TeleAI-UAGI/telemem&type=date&legend=top-left)
617
+
618
+ ---
619
+
620
+ <div align="center">
621
+
622
+ **If you find this project helpful, please give us a ⭐️.**
623
+
624
+ Made with ❤️ by the Ubiquitous AGI team at TeleAI.
625
+
626
+ </div>
627
+
628
+ <div align="center" style="margin-top: 10px;">
629
+ <img src="assets/TeleAI.jpg" alt="TeleAI Logo" height="120px" />
630
+ &nbsp;&nbsp;&nbsp;
631
+ <img src="assets/TeleMem.png" alt="TeleMem Logo" height="120px" />
632
+ </div>
633
+
634
+
635
+
636
+