A "self-consistent" memory system for AI agents.

中文文档

Octomem is inspired by the octopus brain: 9 brains (1 central + 8 arms), distributed yet self-consistent.

Most AI agent memory systems do one thing: store and retrieve. Write in, read out, done.

The problem? Memories pile up. Contradictions accumulate. Duplicates keep growing. What agents are facing is memory chaos that leads to a split personality.

I want my agent to have its own worldview — its own take on things — not a bot that says "both sides are fine."

• Markdown as the source of truth — your memories are always readable, exportable, and portable.
• Full CLI support — because this is an agent memory system, don't forget that.
• SQLite + vectors + segmentation — looks familiar? Double the OpenClaw friendliness!

The core insight: validating before writing is more important than retrieving after storing.

PS: Of course, "dreaming" — the romantically packaged periodic cleanup — Octomem will do that too.

Your memories are never locked in a proprietary format.

Markdown files are the permanent, human-readable archive. The database is just a search index.

Input → Format → Structurize → Validate → Merge → Index
                      ↑           ↑
                      │           └── the core differentiator
                      └── LLM-powered extraction

Before any memory is stored, Octomem searches existing memories for similar content, then uses an LLM to classify the relationship:

• CONTRADICTS → flag as conflict, block write
• OVERLAPS → trigger merge with existing memory
• INDEPENDENT → safe to store

This means your memory base stays clean and consistent — no duplicates, no contradictions. Conflicting information gets caught at the door.

Export = copy markdown files. Database corrupted? Rebuild the index.

Every memory gets a confidence score (0.0 – 1.0):

• validate() assigns the initial score
• merge() adjusts it based on overlap quality
• ≤ 0.1 → candidate for archival

• Node.js >= 20
• An embedding service (pick one):
  • Ollama (local, free, recommended)
  • SiliconFlow (cloud, free tier)
  • OpenAI (cloud, paid)
• An OpenAI-compatible LLM API key (for validate & merge)

git clone https://github.com/Lision/octomem.git
cd octomem
npm install
npm run build

cp .env.example .env

Edit .env:

# LLM (for validate & merge — any OpenAI-compatible API)
OPENAI_API_KEY=sk-your-key
# LLM_BASE_URL=https://your-provider.com/v1   # optional, defaults to OpenAI
# LLM_MODEL=gpt-4o-mini                        # optional

# Embedding (for search & similarity — independent from LLM)
# Option A: Ollama (recommended, free)
#   1. Install: https://ollama.com
#   2. Pull model: ollama pull bge-m3
EMBEDDING_BASE_URL=http://localhost:11434/v1
EMBEDDING_MODEL=bge-m3

# Initialize memory store
npx octomem init

# Add a memory
npx octomem add --text "Rust prioritizes safety, Go prioritizes simplicity."

# Search
npx octomem search "programming languages"

# Add a similar memory — watch merge kick in
npx octomem add --text "Go is simpler, Rust is safer but steeper learning curve."

# Check for conflicts
npx octomem conflicts

# List tags
npx octomem tags

MIT