Tools
FlockMem
By โฆ FlockMem is a lightweight, local-first long-term collective memory bus for multi-agents, optimized for edge deployment with a minimal memory footprint under 50MB. It combines text-based, vector similarity, and knowledge graph retrieval with traceable citations.
Install
npm install openclaw-flockmemConfiguration 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
}
}README
# <img src="https://raw.githubusercontent.com/gengxy1216/FlockMem/main/docs/assets/flockmem-icon.svg" alt="FlockMem logo" width="32" /> FlockMem
> Lightweight local-first memory system for AI agents โจ
[](LICENSE)
[](pyproject.toml)
[](https://zread.ai/gengxy1216/FlockMem)
<p align="center">
<img src="docs/assets/flockmem-banner.svg" alt="FlockMem banner" />
</p>
English | [็ฎไฝไธญๆ](README.zh-CN.md)
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`:
```bash
pip install flockmem
flockmem
```
`npm`:
```bash
npm install openclaw-flockmem
```
`openclaw plugin`:
```bash
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:
```bash
# Windows
start_flockmem.bat
# Linux/macOS
bash scripts/start.sh
```
### Manual Install
```bash
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](docs/api-reference.md)
```bash
# 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:
```bash
python skills/flockmem-mcp-integration/scripts/run_flockmem_mcp.py
```
Generate a client config snippet:
```bash
python skills/flockmem-mcp-integration/scripts/generate_mcp_config.py
```
Run MCP integration test:
```bash
pytest -q tests/test_flockmem_mcp_server.py
```
Package the MCP skill as a distributable artifact:
```bash
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
powershell -ExecutionPolicy Bypass -File integrations/openclaw-plugin/install.ps1
```
```bash
bash integrations/openclaw-plugin/install.sh
```
Or install distributed plugin package:
```bash
openclaw plugins install openclaw-flockmem
openclaw plugins enable flockmem-memory
```
Advanced entry example:
```json
{
"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:
```bash
# 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`)
... (truncated)
tools
Comments
Sign in to leave a comment