TeleMem: a mem0-compatible memory layer with per-character isolation and a video pipeline

The problem TeleMem targets: memory that leaks between characters and forgets video

Most agent memory libraries treat a user as a single stream. Every fact extracted from a conversation lands in one namespace, and retrieval ranks all of it together. That is fine for a support bot with one persona. It breaks in role-play, companion AI, NPCs and multi-persona assistants, where the same user talks to several characters and the memory of one must not surface inside another. The README states that TeleMem is "the only open-source memory layer that automatically builds isolated, per-character memory profiles", which is a claim about the field rather than a verified comparison, but the design goal is clear.

The second problem is modality. A memory layer that only ingests text cannot answer questions about a video. TeleMem's README describes a pipeline of video frame extraction, caption generation and vector database construction, so an agent can "store, retrieve, and reason over video content just like handling text memories". The target user is a Python developer building a conversational agent that needs either of those two things, and who does not want to leave the mem0 API to get them.

How the mem0 drop-in works, and why the version pin matters

The compatibility story is one line: `import telemem as mem0`. According to the README, `add()` and `search()` accept the same arguments and return the same `{"results": [...]}` shape, so existing Mem0 code keeps working. That is the whole pitch for migration cost.

The mechanism behind it is less tidy. The pyproject.toml comment says TeleMem "extends mem0's Memory class and calls some private helpers (_create_memory, _search_vector_store, _create_procedural_memory), so the supported range is pinned to the tested minor series". The dependency is therefore `mem0ai>=2.0,<2.1`. Underscore-prefixed methods are not a public API. If mem0 renames or changes the signature of any of the three in a 2.1 release, TeleMem cannot simply widen the pin; it has to track the change. That is a deliberate trade: instant API compatibility in exchange for coupling to internals.

On top of that base, TeleMem adds semantic deduplication, buffering and batch writing for retrieval, and the character isolation layer. The default local stack is Qwen plus FAISS, and the README says it runs end to end on your hardware with no cloud service and no data leaving the machine. The MCP surface exposes 8 memory tools, registered under `mcp__telemem__*` when started through the DeepSeek Harness patch added in v1.10.0.

Installing TeleMem and running a first add and search

The package is on PyPI, and the README gives `pip install telemem` as the install line. The project metadata requires Python 3.10 or newer and lists 3.10, 3.11 and 3.12 in its classifiers.

pip install telemem

After that, the compatibility claim is testable in one file. The README's own example is the import line, and because the return shape is documented as `{"results": [...]}`, any code you already wrote against mem0 should read the same keys.

import telemem as mem0

If you prefer not to install anything, v1.7.1 put TeleMem on the official MCP registry, and the README advertises `uvx telemem` as the zero-install way to run the memory server. The Dockerfile builds the MCP server image from the local source tree, and its header comments give the build and run lines, including the stdio form and the streamable-http form on port 8421.

docker build -t telemem-mcp .
docker run -i --rm -e OPENAI_API_KEY telemem-mcp
docker run -p 8421:8421 --rm telemem-mcp --transport streamable-http --host 0.0.0.0

The Dockerfile notes that the server starts without any API key because the Memory instance is created lazily on the first tool call, so introspection works before you supply credentials. The stdio example forwards `OPENAI_API_KEY` from your environment. The repository also ships LangChain and LlamaIndex examples, and v1.6.0 added Ollama, DeepSeek and Kimi configs, so a non-OpenAI provider is a supported path rather than a workaround.

Where TeleMem is the wrong tool

The private-helper dependency is the first real limitation, and it is structural rather than cosmetic. A memory layer that reaches into another library's underscore methods inherits that library's release cadence. If your project needs a memory backend whose contract you control, or if you vendor dependencies and audit them, this design will keep pulling you back into mem0's changelog.

The second limitation is the mem0 assumption itself. There is no documented standalone mode that drops mem0ai entirely; the package depends on it. That means you carry mem0's own dependency tree, which in this repository's requirements.txt includes qdrant-client and sqlalchemy alongside faiss-cpu, even if you only ever use the local FAISS path.

Third, the project describes itself in pyproject.toml as "Development Status :: 4 - Beta". The 1.8.0 release notes describe a character-memory extraction fix and say that `infer=False`, `prompt` and `memory_type` are "now fully honored", which tells you those arguments were not honored before. If you are on an older release, that is a concrete reason to upgrade rather than a general caution.

Finally, this is a Python package. If your agent runtime is TypeScript, Go or Java, the drop-in story does not apply to you, and the MCP server is the only realistic integration point.

TeleMem against Mem0 and Memobase

The obvious alternative is Mem0 itself, and the difference is not a feature list. Mem0 is the layer TeleMem extends; choosing Mem0 means choosing the public API and its release schedule, while choosing TeleMem means choosing character isolation, the video pipeline and local-first defaults on top of that same base. If you do not need per-character profiles or video memories, the extra layer buys you nothing and costs you the version pin.

Memobase is the other name that comes up in searches around this project, and the difference in approach is worth stating plainly. Memobase is a separate memory system with its own API and its own storage model, so adopting it is a migration. TeleMem's bet is the opposite: no migration at all, because your existing mem0 call sites stay as they are. That is a real advantage for a running service and a real disadvantage for anyone who wants to leave the mem0 lineage behind.

The video pipeline is the capability with no direct equivalent in the mem0 API surface described here. The README describes ReAct-style multi-step video QA over the stored frames and captions. Note that opencv-python-headless and yt-dlp appear in requirements.txt, so the video path carries its own dependencies and is not part of a minimal text-only install.

Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-07, so it is current. The release history is dense: v1.10.0 on 2026-08-15, v1.9.0 on 2026-08-06, v1.8.0 on 2026-07-11, with earlier releases reaching back to v1.0.0 on 2025-12-05. That cadence is the upgrade cost. Two of the recent releases track external standards, the MCP Python SDK v2 migration for spec 2026-07-28 and the DeepSeek Harness support, so some upgrades are driven by other projects' timelines rather than TeleMem's own roadmap.

The licence is Apache-2.0, declared both in pyproject.toml and in the LICENSE file. That is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your own code. The one thing to check is the interaction with mem0ai, which TeleMem depends on and whose licence is not stated in this material. If you redistribute a bundled environment, verify the terms of every dependency in requirements.txt rather than assuming TeleMem's Apache-2.0 covers the whole tree. This is not legal advice; read the licences yourself.

On telemetry, the v1.8.0 notes say telemetry is disabled by default, and posthog still appears in requirements.txt. Disabled by default is the right setting for a memory layer, but it is a setting, so treat it as one you can verify rather than one you can assume.

Editorial conclusion

Adopt TeleMem if you are already on mem0 and want character isolation or video memories without rewriting call sites, and you accept the mem0ai>=2.0,<2.1 pin. Do not adopt it if you need a stable private-API contract from your memory layer, or if your stack is not Python. Before committing, read telemem/ against the mem0ai version you actually have installed and check whether _create_memory, _search_vector_store and _create_procedural_memory still exist with the signatures TeleMem calls.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. TeleAI-UAGI/telemem on GitHub