🧠 OpenMemory

Give your AI assistant persistent memory that survives across sessions.

OpenMemory is an open-source memory server that lets AI assistants remember facts, keep diaries, and maintain context across conversations — backed by SQLite and exposed via REST API + MCP.

---

Why OpenMemory?

Every AI conversation starts from scratch. OpenMemory fixes that.

• 🔒 Persistent memory — facts, preferences, and context survive across sessions
• 📓 Automatic diary — every save appends a timestamped diary entry
• 🔌 MCP Server — plug directly into Claude Code, Cursor, Windsurf, or any MCP client
• 🌐 REST API — integrate with any language or platform via HTTP
• 💻 CLI — manage memory from the terminal
• 🐳 Docker-ready — one docker compose up to deploy
• ⚡ Zero config — SQLite database, no external services needed

Quick Start

# Clone and install
git clone https://github.com/naimkatiman/OpenMemory.git
cd OpenMemory
npm install

# Start the server
npm run dev

Server starts at http://localhost:8787 — Swagger docs at http://localhost:8787/docs

Hybrid Mode (Central + Project Instances)

Run isolated instances with built-in presets:

# central user memory (port 8787)
npm run dev:central

# project memory instances (ports 8788, 8789)
npm run dev:project-a
npm run dev:project-b

See full guide: hybrid-setup.md

Docker variant:

docker compose -f docker-compose.hybrid.yml up -d

Try It Out

# Save a memory
curl -X POST http://localhost:8787/v1/save \
  -H "Content-Type: application/json" \
  -d '{
    "memory_updates": [
      {"scope": "preferences", "key": "language", "value": "TypeScript"},
      {"scope": "preferences", "key": "editor", "value": "VS Code"}
    ],
    "summary": "User prefers TypeScript and VS Code"
  }'

# Recall memories
curl http://localhost:8787/v1/memory

# Review diary entries
curl http://localhost:8787/v1/diary/recent?limit=5

# Switch profiles
curl -X POST http://localhost:8787/v1/profiles/switch \
  -H "Content-Type: application/json" \
  -d '{"profile": "assistant"}'

Use via CLI

npm run cli -- save --update preferences:language:TypeScript --summary "setup complete"
npm run cli -- review --limit 5
npm run cli -- switch assistant
npm run cli -- execute "Summarize today's progress"

MCP Server (Claude Code / Cursor / Windsurf)

Add to your MCP config (e.g. ~/.cursor/mcp.json or Claude Code settings):

{
  "mcpServers": {
    "memorycore": {
      "command": "node",
      "args": ["dist/src/mcp.js"],
      "cwd": "/path/to/OpenMemory"
    }
  }
}

Build first: npm run build

For hybrid central/project MCP wiring, see hybrid-setup.md.

Available MCP tools:

Tool	Description
memory_save	Save memory facts and diary entry
memory_recall	Retrieve stored memory facts
diary_review	Read recent diary entries
profile_switch	Switch between assistant profiles
profile_list	List all profiles and capabilities

Architecture

┌─────────────────────────────────────────┐
│             Client Layer                │
│  MCP Server │ REST API │ CLI            │
├─────────────────────────────────────────┤
│           Service Layer                 │
│  Command Engine │ Profile Manager       │
├─────────────────────────────────────────┤
│           Storage Layer                 │
│     SQLite (better-sqlite3)             │
│  ┌──────────┬──────────┬──────────┐     │
│  │ Memory   │ Diary    │ Command  │     │
│  │ Facts    │ Entries  │ Log      │     │
│  └──────────┴──────────┴──────────┘     │
└─────────────────────────────────────────┘

File Structure

OpenMemory/
├── src/
│   ├── server.ts          # Fastify server bootstrap
│   ├── api.ts             # REST route definitions
│   ├── mcp.ts             # MCP server for AI editors
│   ├── service.ts         # Command engine + profile logic
│   ├── storage.ts         # SQLite persistence layer
│   ├── schemas.ts         # Zod validation schemas
│   ├── config.ts          # Environment config
│   └── cli.ts             # CLI runner
├── examples/
│   ├── curl-commands.sh   # Example API calls
│   └── js-client.mjs      # JavaScript client example
├── tests/
├── Dockerfile
├── docker-compose.yml
└── package.json

Profiles

MemoryCore supports dual assistant profiles that share the same memory backend:

Profile	Mode	Use Case
primary	Native Memory	Relationship-first, continuity mode
assistant	Capability Mode	Execution-first, structured mode

Both profiles read/write to the same SQLite database. Switch between them without losing context.

Configure Your Own Profile Names

Set custom names via the API or just use them as aliases:

# The default profiles are "primary" and "assistant"
# You can switch using any registered alias
curl -X POST http://localhost:8787/v1/profiles/switch \
  -H "Content-Type: application/json" \
  -d '{"profile": "primary"}'

Docker Deployment

# Start with Docker Compose
docker compose up -d

# Or build manually
docker build -t memorycore .
docker run -p 8787:8787 -v memorycore-data:/app/runtime memorycore

Configuration

Copy .env.example to .env and adjust:

Variable	Default	Description
OPENCLAW_HOST	127.0.0.1	Server bind address
OPENCLAW_PORT	8787	Server port
OPENCLAW_INSTANCE	default	Instance label (e.g. central, project-a)
OPENCLAW_DB_PATH	./runtime/openclaw.db	SQLite database path
OPENCLAW_DEFAULT_SCOPE	general	Scope used when update scope is omitted
OPENCLAW_ALLOWED_SCOPE_PREFIXES	(empty)	Comma-separated allowed scope prefixes
OPENCLAW_API_KEY	(empty)	API key for auth (set in production)
OPENCLAW_CORS_ORIGIN	*	CORS allowed origin

API Reference

Full OpenAPI docs available at http://localhost:8787/docs when running.

Method	Endpoint	Description
GET	/health	Health check + active profile
GET	/v1/profiles	List profiles
POST	/v1/profiles/switch	Switch active profile
GET	/v1/capabilities	Show profile capabilities
GET	/v1/memory	List memory facts
POST	/v1/save	Save memory + diary entry
GET	/v1/diary/recent	Recent diary entries
POST	/v1/command	Run a named command
POST	/v1/execute	Execute an objective

Feature Modules

Module	Status	Description
Echo Memory Recall	✅ Active	Semantic memory search and recall
LRU Project Management	✅ Active	Track active projects with LRU eviction
Time-based Awareness	✅ Active	Time-aware context and reminders
Skill Plugin System	✅ Active	Extensible skill plugins for AI assistants

Contributing

See CONTRIBUTING.md for guidelines. Issues and PRs welcome!

Contributors

• Kiyoraka (Afif Maahi) - Project creator and lead maintainer
• naimkatiman (Naim Katiman) - Contributor

License

MIT — use it, fork it, ship it.