Somatic Memory

Self-hosted embodied memory service for OpenClaw and VAGUS workflows.

What this repository contains

Memory API service (src/server.mjs) built on Fastify + Postgres/pgvector
Optional MCP bridge (src/bridge.mjs) for memory tooling
SQL schema + migrations (sql/)
OpenClaw plugin packages (openclaw-plugins/)
Docker and shell deployment helpers

What it is

Somatic Memory is a self-hosted, long-term memory layer for embodied AI agents. It bridges the gap between an AI agent's ephemeral context window and the persistent, body-aware experience of a living person. Rather than just remembering what was said, it remembers what was happening — what the user was doing, where they were, how alert they seemed, and what agent actions worked or failed in those conditions.

The system is purpose-built for the Luna / VAGUS stack: Luna (the OpenClaw agent) gains autobiographical memory grounded in Vicky's real physical context — a memory that persists across sessions and grows richer over time.

---

Architecture Overview

Android Phone (VAGUS app)
        │  MCP over WebSocket
        ▼
   Relay Server
  (session transport)
        │
        ▼
 OpenClaw Gateway  ◄──── three native plugins loaded here
  ├─ vagus-core          (phone connection + live sensor data)
  ├─ somatic-memory      (writes/reads the Postgres memory store)
  └─ working-memory      (compiles prompt-time context from both)
        │
        ▼
Somatic Memory API  (http://localhost:8420)
        │
        ▼
  Postgres + pgvector
  (memories · facts · episodes)

---

Security and sanitization status

This somatic-memory-public package is prepared for public publishing:

Local runtime state is excluded (.openclaw, local DB files, tokens)
Hardcoded auth examples are replaced with placeholders
Secret-bearing files are ignored by default via .gitignore

Before production use, rotate all credentials and generate a unique memory auth token.

Quick start

1. Prerequisites

Node.js 20+
PostgreSQL 15+ with pgvector
npm

2. Configure environment

cp .env.example .env

Required values to set in .env:

MEMORY_AUTH_TOKEN
EMBED_API_KEY
LLM_API_KEY

3. Initialize database

createdb somatic_memory
psql -d somatic_memory -f sql/001_schema.sql
psql -d somatic_memory -f sql/002_compiled_context.sql

4. Run service

npm install
npm run server

Health check:

curl http://127.0.0.1:8420/health

Docker compose workflow

docker compose up -d postgres
docker compose exec postgres psql -U soma -d somatic_memory -f /sql/001_schema.sql
docker compose exec postgres psql -U soma -d somatic_memory -f /sql/002_compiled_context.sql
docker compose up -d memory

OpenClaw integration

Use plugin entries from config/openclaw.json5.example.

Documentation:

Repository structure

somatic-memory-public/
  config/
  docs/
  openclaw-plugins/
  scripts/
  sql/
  src/

License

MIT. See LICENSE.

vagus-core

Summary

Install to Claude Code