flockmem 0.2.0

Lightweight long-term memory system for local/edge AI agents

FlockMem

Lightweight local-first memory system for AI agents ✨

English | 简体中文

FlockMem is a lightweight, local-first long-term memory system designed for AI agents. It is also built as a memory infrastructure layer for multi-agent collaboration. With edge deployment in mind, it runs with a minimal memory footprint under 50MB, making it suitable for resource-constrained environments 🖥️

Why FlockMem? 💡

• 🧱 Multi-Agent Memory Infrastructure - One shared memory substrate across agents, runtimes, and workflows
• 🔄 Local-first - No cloud dependencies, runs entirely on your device
• 🔍 Hybrid Retrieval - Text + Vector + Graph search with citation traces
• 🧠 Structured + Episodic Memory - Entities, relationships, and conversation memories in one system
• ⚡ Lightweight - Under 50MB memory usage, suitable for edge devices
• 🔌 Integration-ready - REST API + MCP bridge + OpenClaw plugin
• 🚀 One-click Install - Get started in seconds

Key Positioning: Memory Infrastructure for Multi-Agent Collaboration

FlockMem is not just a memory store for a single assistant. It provides:

• Shared memory infrastructure for multiple agents via REST, MCP, and plugin bridges
• Controlled collaboration boundaries with role-based, shared-group, and per-user memory strategies
• Retrieval traces and citations for auditability and easier debugging
• Local-first deployment with predictable cost, data ownership, and operational simplicity

Quick Start ⚡

One-click Install

pip:

pip install flockmem
flockmem

npm:

npm install openclaw-flockmem

openclaw plugin:

openclaw plugins install openclaw-flockmem
openclaw plugins enable flockmem-memory

Local install (kept):

Platform	Command
🪟 Windows	powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -RunAfterInstall
🐧 Linux	bash scripts/install.sh --run
🍎 macOS	bash scripts/install.sh --run

Or use the launcher:

# Windows
start_flockmem.bat

# Linux/macOS
bash scripts/start.sh

Manual Install

pip install -e .
flockmem

Access the UI 🌐

Open your browser:

http://127.0.0.1:20195/ui

🔐 Default Credentials: admin / admin123

Features 🎯

Feature	Description
📝 Memory Storage	Store and manage conversation memories
🔎 Semantic Search	Find relevant memories using vector similarity
🕸️ Graph Search	Explore entity relationships in knowledge graph
💬 Chat with Memory	Context-aware conversations with retrieval traces
⚙️ Runtime Config	Change providers and settings on-the-fly

API Overview 📡

For complete API documentation, see API Reference

# Health check
GET /health

# Store memory
POST /api/v1/memories

# Search memories
GET /api/v1/memories/search

# Chat with context
POST /api/v1/chat/simple

# Graph queries
GET /api/v1/graph/search
GET /api/v1/graph/neighbors

MCP Integration 🔌

FlockMem now includes a standalone MCP bridge server for cross-agent integration:

• Server path: integrations/flockmem-mcp/server.py
• Skill path: skills/flockmem-mcp-integration

Run the MCP bridge:

python skills/flockmem-mcp-integration/scripts/run_flockmem_mcp.py

Generate a client config snippet:

python skills/flockmem-mcp-integration/scripts/generate_mcp_config.py

Run MCP integration test:

pytest -q tests/test_flockmem_mcp_server.py

Package the MCP skill as a distributable artifact:

python C:/Users/user/.agents/skills/skill-creator/scripts/package_skill.py skills/flockmem-mcp-integration dist

Packaged artifact:

• dist/flockmem-mcp-integration.skill

Environment variables (optional):

• MINIMEM_BASE_URL (default: http://127.0.0.1:20195)
• MINIMEM_USER_ID
• MINIMEM_GROUP_ID
• MINIMEM_BEARER_TOKEN or MINIMEM_BASIC_USER + MINIMEM_BASIC_PASSWORD

OpenClaw Plugin Integration

FlockMem also provides a lightweight OpenClaw plugin bridge:

• Plugin path: integrations/openclaw-plugin
• Plugin manifest: integrations/openclaw-plugin/openclaw.plugin.json
• Plugin doc: integrations/openclaw-plugin/README.md
• Policy template: integrations/openclaw-plugin/examples/AGENTS.memory-policy.md

Core capabilities:

• write dialogue / bot profile / context compression into FlockMem
• retrieve memory by strategy (keyword/vector/hybrid/rrf/agentic)
• return context_for_agent for prompt injection
• optional auto capture (agent_end) and auto inject (before_agent_start)
• role-based / shared / per-user group strategies

One-command install:

powershell -ExecutionPolicy Bypass -File integrations/openclaw-plugin/install.ps1

bash integrations/openclaw-plugin/install.sh

Or install distributed plugin package:

openclaw plugins install openclaw-flockmem
openclaw plugins enable flockmem-memory

Advanced entry example:

{
  "path": "C:/path/to/flockmem/integrations/openclaw-plugin",
  "enabled": true,
  "config": {
    "baseUrl": "http://127.0.0.1:20195",
    "groupStrategy": "per_role",
    "sharedGroupId": "shared:team",
    "autoSenderFromAgent": true,
    "autoInjectOnStart": true,
    "autoCaptureOnEnd": true
  }
}

Architecture 🏗️

┌─────────────────────────────────────┐
│            FlockMem UI               │
├─────────────────────────────────────┤
│            REST API                 │
├──────────────┬──────────────────────┤
│   Retrieval  │    Extraction       │
│   (Fusion)   │    (Atomic Facts)   │
├──────────────┼──────────────────────┤
│   Vector DB  │   Graph Store        │
│  (LanceDB)   │   (Local Persistent) │
├──────────────┴──────────────────────┤
│          SQLite (Metadata)          │
└─────────────────────────────────────┘

Memory Tiering (L0 -> L2)

FlockMem uses progressive memory tiers to balance simplicity, recall quality, and retrieval performance:

Tier	Name	Core Storage	Retrieval Role
L0	Plain Text	SQLite (episodic_memory)	Full-fidelity source of truth, keyword/metadata recall
L0.5	Vector-Text (Hot)	Local vector cache (jsonl + snapshot)	Fast local semantic recall and restart-safe warm cache
L1	Vector (Persistent)	LanceDB (memory_vector_index)	ANN-style semantic retrieval for higher-importance memories
L2	Graph	Local graph triples store	Structured relation recall and graph expansion

Retrieval Flow

1. Query enters policy/selector layer.
2. Keyword + vector recall run in hybrid mode (L0 + L0.5 + L1).
3. Graph evidence from L2 is merged when enabled.
4. Final hits are reranked and rendered with query-aware citation snippets.

Configuration ⚙️

Set environment variables to configure providers:

# Chat provider
LITE_CHAT_PROVIDER=openai
LITE_CHAT_MODEL=gpt-4o-mini

# Embedding provider
LITE_EMBEDDING_PROVIDER=openai
LITE_EMBEDDING_MODEL=text-embedding-3-small

# Graph module (optional)
LITE_GRAPH_ENABLED=true

# Retrieval profile
LITE_RETRIEVAL_PROFILE=agentic

  # Hybrid vector persistence (partial to LanceDB)
  LITE_VECTOR_LANCEDB_ENABLED=true
  LITE_VECTOR_LANCEDB_MIN_IMPORTANCE=0.72

  # Admin protection for sensitive config APIs
  LITE_ADMIN_TOKEN=change-me
  LITE_ADMIN_ALLOW_LOCALHOST=true
  
  # Retrieval latency/recall tuning (edge-side)
  LITE_SEARCH_BUDGET_FACTOR=4
LITE_SEARCH_MIN_PROBE_K=12
LITE_KEYWORD_CONFIDENT_BEST_SCORE=9.0
LITE_KEYWORD_CONFIDENT_KTH_SCORE=2.8
LITE_SEMANTIC_VECTOR_BUDGET_CAP=32
LITE_SEMANTIC_KEYWORD_BUDGET_CAP=16
  LITE_QUERY_EMBED_CACHE_SIZE=256
  LITE_QUERY_EMBED_CACHE_TTL_SEC=900

• Sensitive endpoints (/api/v1/config/raw, /api/v1/model-config*) accept Authorization: Bearer <LITE_ADMIN_TOKEN> or X-API-Key.
• When LITE_ADMIN_TOKEN is empty, localhost access is allowed by default (LITE_ADMIN_ALLOW_LOCALHOST=true).

Default local storage location (when LITE_DATA_DIR is not set):

• Windows: %LOCALAPPDATA%\\MiniMem (kept for backward compatibility)
• Linux/macOS: $XDG_DATA_HOME/minimem or ~/.local/share/minimem

Tech Stack 🛠️

• FastAPI - Modern async web framework
• SQLite - Local structured data
• LanceDB - High-performance vector database
• Local Graph Store - Persistent triple storage and graph retrieval

Acknowledgments 🙏

FlockMem builds on the shoulders of giants ❤️

• EverMemOs - Original inspiration for agent memory systems
• LanceDB - Developer-friendly vector database
• SQLite - The most used database in the world

License 📄

MIT License - see LICENSE for details.

---

Made with ❤️ for AI agents everywhere 🤖