Skip to content

README.md

Latest commit

 

History

History
254 lines (193 loc) · 8.22 KB

README.md

File metadata and controls

254 lines (193 loc) · 8.22 KB

🧠 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.

License: MIT TypeScript Node.js

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.