https://github.com/wikieden/tempomem

Spatial memory layer for AI agents — RGB-D / point clouds to a persistent, queryable, LLM-native 3D scene graph. Mem0 for 3D space.
https://github.com/wikieden/tempomem

3d ai-agents embodied-ai llm point-cloud rgbd robotics scene-graph spatial-memory sqlite

Last synced: about 19 hours ago
JSON representation

Spatial memory layer for AI agents — RGB-D / point clouds to a persistent, queryable, LLM-native 3D scene graph. Mem0 for 3D space.

• Host: GitHub
• URL: https://github.com/wikieden/tempomem
• Owner: wikieden
• License: apache-2.0
• Created: 2026-05-29T06:23:36.000Z (about 1 month ago)
• Default Branch: main
• Last Pushed: 2026-07-02T12:38:53.000Z (8 days ago)
• Last Synced: 2026-07-02T14:22:50.393Z (8 days ago)
• Topics: 3d, ai-agents, embodied-ai, llm, point-cloud, rgbd, robotics, scene-graph, spatial-memory, sqlite
• Language: Python
• Homepage: https://github.com/wikieden/spatialmem
• Size: 278 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

          
> 🌐 **English** · [中文](README.zh.md)

# Chronotope

[![CI](https://github.com/wikieden/tempomem/actions/workflows/ci.yml/badge.svg)](https://github.com/wikieden/tempomem/actions/workflows/ci.yml)

[![PyPI](https://img.shields.io/pypi/v/tempomem)](https://pypi.org/project/tempomem/)

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)

[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

Spatial memory layer for AI agents. Turn RGB-D / point clouds into a persistent, queryable, LLM-native 3D scene graph — in one pip install.

> **Positioning:** Mem0 for 3D space. ConceptGraphs / Hydra do perception; Mem0 does text memory; nothing today bridges perception → persistent, agent-queryable spatial memory. We fill that slot.

## Quickstart

```python

from tempomem import TempoMem, Detection

# Detections-in (BYO perception): supply label + 3D bbox + feature vector.

mem = TempoMem.open("kitchen.smem", embedding_dim=512)

mem.add_detections([

    Detection("mug", feat, center_xyz=(1.2, 0.3, 0.9),

              bbox_min=(1.15, 0.25, 0.85), bbox_max=(1.25, 0.35, 0.95)),

])

mem.commit()                       # runs the fusion arbiter — incremental dedup

mem.recent(n=5)                                    # temporal

mem.spatial(near=(1.0, 0.0, 1.0), radius=2.0)      # spatial

prompt = mem.serialize(format="prompt")            # graph -> compact LLM text

# Natural-language semantic search + answer need an encoder/verbalizer:

mem = TempoMem.open("kitchen.smem", embedding_dim=512,

                         encoder=my_clip, verbalizer=my_llm)

mem.semantic("coffee mug")                         # cosine over node features

mem.answer("where is the mug?")                    # retrieve -> prompt -> BYO LLM

# Streaming RGB-D (needs a PerceptionAdapter; ConceptGraphs adapter is WIP):

# mem = TempoMem.open(..., adapter=MyAdapter())

# mem.add_frame(rgb, depth, pose); mem.commit()

```

Runnable, no GPU: `python examples/01_quickstart.py` and `examples/02_query_and_answer.py`.

## What works today

| Capability | Status |

|---|---|

| Single-file `.smem` SQLite store, persist/reopen | ✅ |

| `add_detections` + incremental fusion (dedup, merge, reject) | ✅ |

| Spatial / temporal / keyword query | ✅ |

| Semantic query via BYO `Encoder` (`OpenClipEncoder` in `[clip]`) | ✅ |

| sqlite-vec ANN index (`[vec]`), linear fallback | ✅ |

| `answer()` via BYO `Verbalizer` (OpenAI / Anthropic / Ollama) | ✅ |

| `decay()` + `forget()` + `resplit()` memory hygiene | ✅ |

| `consolidate()` + `salient()` memory consolidation | ✅ |

| Hierarchy / rooms — `define_region()` + `contents()` | ✅ |

| Spatial relations — `relate()` + `related()` (`near`/`on`/`under`) | ✅ |

| Relational NL query — `query("what's on the table")` traverses edges | ✅ |

| `update()` + `history()` (Mem0-style correction + observation trail) | ✅ |

| Multi-session merge — `merge(other.smem)` | ✅ |

| Change detection — `moved()` / `changes()` / `stale()` | ✅ |

| `serialize(format="prompt"/"json")` for LLM hand-off | ✅ |

| Token-budgeted prompt — `serialize(format="prompt", max_tokens=N)` | ✅ |

| `recall_at_k` eval harness | ✅ |

| Read-only HTML viewer — `tempomem viz store.smem -o scene.html` | ✅ |

| RGB-D `add_frame` via `PerceptionAdapter` protocol | ✅ seam; ConceptGraphs adapter WIP (CUDA) |

Core install is **numpy-only**. Heavy backends live behind extras: `[clip]`, `[vec]`, `[perception]`.

## Repo Layout

```

docs/        product + engineering decisions (read first)

spec/        normative API / schema specs

src/tempomem/   Python package (lib)

examples/    runnable demos (real + simulated)

tests/

```

## Status

Pre-alpha. Public design phase. Read in order:

- [docs/00-VISION.md](docs/en/00-VISION.md) — what & why

- [docs/01-POSITIONING.md](docs/en/01-POSITIONING.md) — competitors & wedge

- [docs/02-ARCHITECTURE.md](docs/en/02-ARCHITECTURE.md) — layers & dataflow

- [docs/03-ROADMAP.md](docs/en/03-ROADMAP.md) — milestones

- [docs/04-MVP-SCOPE.md](docs/en/04-MVP-SCOPE.md) — first deliverable

- [spec/API.md](spec/API.md) — Python SDK contract

- [spec/SCHEMA.md](spec/SCHEMA.md) — scene-graph schema

- [spec/FUSION-ARBITER.md](spec/FUSION-ARBITER.md) — node merging algorithm

- [spec/QUERY-ROUTER.md](spec/QUERY-ROUTER.md) — query → retrieval

- [spec/ENGINEERING.md](spec/ENGINEERING.md) — coding standards / CI

## License

Apache-2.0 — see [LICENSE](LICENSE).