<p align="center">
<h1 align="center">🧠 OpenClaw FCMA</h1>
<p align="center"><strong>The Memory Layer That Makes AI Actually Remember</strong></p>
<p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#architecture">Architecture</a> •
<a href="#28-mcp-tools">Tools</a> •
<a href="#api-usage">API</a> •
<a href="#contributing">Contributing</a>
</p>
</p>

<p align="center">





</p>

---

The Problem

Every time you start a new conversation with an AI, it forgets everything. Your name, your project, your preferences — all gone. You repeat yourself endlessly.

OpenClaw FCMA fixes this. It gives AI a persistent, structured memory — not just a bigger notepad, but a brain.

Architecture

┌─────────────────────────────────────────────────┐
│  L1 · Scratchpad  ·  Working Memory (this turn) │
├─────────────────────────────────────────────────┤
│  L2 · Journal     ·  Episodic Memory (FAISS)    │
├─────────────────────────────────────────────────┤
│  L3 · Mind        ·  Knowledge Graph (Neo4j)    │
├─────────────────────────────────────────────────┤
│  L4 · Library     ·  Your Documents (FAISS+SQL) │
├─────────────────────────────────────────────────┤
│  L5 · World State ·  Live Facts (Key-Value)     │
├─────────────────────────────────────────────────┤
│  L6 · Ledger      ·  Session Notes (.md files)  │
└─────────────────────────────────────────────────┘

vs. Traditional RAG:

| Feature | RAG | OpenClaw FCMA |
|---------|-----|---------------|
| Structure | Flat vector search | 6-tier hierarchy |
| Relationships | None | Knowledge graph |
| Learning | Static | Surprise-driven |
| Documents | Vector chaos at 25+ PDFs | Parent-child indexing |
| User isolation | DIY | Built-in |
| GDPR | DIY | Built-in export + delete |

Quick Start

1. Install

git clone https://github.com/MohitDhawane/openclaw-fcma.git
cd openclaw-fcma
pip install -e ".[dev]"

2. Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openclaw-fcma": {
      "command": "python",
      "args": ["-m", "openclaw.mcp_server"],
      "cwd": "/path/to/openclaw-fcma"
    }
  }
}

3. Restart Claude Desktop

That's it. Claude now has persistent memory with 28 tools.

4. Try It

You:    "Remember that my project uses Next.js 14 with PostgreSQL"
Claude: ✅ Stored in Journal + SQL. Total episodes: 1
--- [New conversation, days later] ---
You:    "What stack am I using?"

Claude: 🔍 Your project uses Next.js 14 with PostgreSQL.

28 MCP Tools

L2 Journal — Episodic Memory

| Tool | Description | |------|-------------| | memory_store | Store a memory episode | | memory_recall | Recall relevant memories by query |

L3 Mind — Knowledge Graph

| Tool | Description | |------|-------------| | mind_add_node | Add concept/entity/action nodes | | mind_add_edge | Create relationships between nodes | | mind_query | Traverse the knowledge graph | | mind_decay | Apply forgetting curve (neural decay) | | mind_prune | Remove low-weight forgotten nodes |

L4 Library — Document Storage

| Tool | Description | |------|-------------| | library_upload | Upload text documents | | library_search | Vector search across documents | | library_ingest | Full pipeline: chunk → embed → index | | library_smart_search | Two-stage retrieval with re-ranking |

L5 World State — Live Facts

| Tool | Description | |------|-------------| | world_state_set | Set key-value pairs | | world_state_get | Get values by key |

L6 Ledger — Session Summaries

| Tool | Description | |------|-------------| | ledger_save | Save session summary as .md file | | ledger_list | List saved session notes | | ledger_read | Read a specific session file | | ledger_context | Get recent context for session recovery |

Discovery

| Tool | Description | |------|-------------| | discovery_investigate | Analyze hollow-focus tokens |

Knowledge Graph Viewer

| Tool | Description | |------|-------------| | graph_view | View graph as markdown/mermaid/json/text | | graph_export | Export graph to file on disk |

User Management & Security

| Tool | Description | |------|-------------| | user_register | Create account with API key | | user_data_export | Export all user data (GDPR) | | user_data_delete | Delete all user data (GDPR) | | db_stats | Database statistics | | audit_log | View data sovereignty audit trail | | auth_login | Exchange API key for JWT token | | auth_token_info | Verify and decode JWT token | | auth_rate_status | Check rate limit status |

API Usage

from openclaw.memory.controller import MemoryController
from openclaw.memory.journal import Journal
from openclaw.memory.library import Library
from openclaw.memory.vector_store import FAISSVectorStore
Initialize
journal = Journal(backend=FAISSVectorStore())
mc = MemoryController(l2_journal=journal)
Store memory
mc.update_memory(
    query="User asked about Kubernetes",
    response="Kubernetes orchestrates containers...",
    surprise_score=0.85,
)
Recall memory
context = mc.synthesize_context("Tell me about containers")

Data Storage

data/
├── openclaw.db          ← SQLite (users, audit, document index)
├── journal/             ← FAISS vectors (episodic memory)
├── library/             ← FAISS vectors (document search)
├── ledger/              ← Session summaries (.md files)
│   └── {user_id}/
│       ├── 2026-02-14_Database_Upgrade.md
│       └── 2026-02-15_API_Design.md
└── graph_exports/       ← Knowledge graph exports
    └── {user_id}/
        └── graph_2026-02-15.md

Security

- JWT Authentication — 24-hour tokens with refresh and revocation
- API Keys — Auto-generated per user (fcma_xxxx...)
- Rate Limiting — Sliding window (60 req/min, configurable)
- GDPR Compliance — Full data export + cascade deletion + audit trail
- Password Hashing — Salted SHA-256

Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| DATABASE_URL | sqlite:///data/openclaw.db | Database connection string |
| FCMA_JWT_SECRET | Random (dev) | JWT signing secret |
| FCMA_API_KEY | None | API key for server auth |
| FCMA_RATE_LIMIT | 60 | Requests per minute per user |

Development

# Install dev dependencies
pip install -e ".[dev]"
Run tests
pytest tests/ -v
Run MCP server (stdio)
python -m openclaw.mcp_server
Run MCP server (HTTP)
python -m openclaw.mcp_server --transport http
MCP Inspector (debug)
mcp dev openclaw/mcp_server.py

Project Structure

openclaw/
├── mcp_server.py           ← MCP server (28 tools, 4 resources)
├── database.py             ← SQL layer (SQLAlchemy)
├── auth.py                 ← JWT + rate limiting
├── memory/
│   ├── controller.py       ← Memory orchestrator
│   ├── journal.py          ← L2 episodic memory
│   ├── mind.py             ← L3 knowledge graph
│   ├── library.py          ← L4 document storage
│   ├── world_state.py      ← L5 key-value state
│   ├── context_ledger.py   ← L6 session summaries
│   ├── vector_store.py     ← FAISS backend
│   ├── graph_viewer.py     ← Graph export (4 formats)
│   ├── discovery.py        ← Curiosity-driven exploration
│   ├── salience.py         ← Surprise scoring
│   └── ingestion.py        ← Document chunking pipeline
└── tests/
    └── ...

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run tests (pytest tests/ -v)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push and open a Pull Request

License

MIT License — see LICENSE for details.

---

<p align="center">
<strong>OpenClaw — Because AI should remember you.</strong>
</p>