smart-memory

# Smart Memory v2 Skill

Smart Memory v2 is a persistent cognitive memory runtime, not a legacy vector-memory CLI.

Core runtime:
- Node adapter: `smart-memory/index.js`
- Local API: `server.py` (FastAPI)
- Orchestrator: `cognitive_memory_system.py`

## Core Capabilities

- Structured long-term memory (`episodic`, `semantic`, `belief`, `goal`)
- Entity-aware retrieval and reranking
- Hot working memory
- Background cognition (reflection, consolidation, decay, conflict resolution)
- Strict token-bounded prompt composition
- Observability endpoints (`/health`, `/memories`, `/memory/{id}`, `/insights/pending`)

## Native OpenClaw Integration (v2.5)

Use the native OpenClaw skill package:
- `skills/smart-memory-v25/index.js`
- Optional hook helper: `skills/smart-memory-v25/openclaw-hooks.js`
- Skill descriptor: `skills/smart-memory-v25/SKILL.md`

Primary exports:
- `createSmartMemorySkill(options)`
- `createOpenClawHooks({ skill, agentIdentity, summarizeWithLLM })`

### Tool Interface (for agent tool use)

1. `memory_search`
- Purpose: query long-term memory.
- Input:
  - `query` (string, required)
  - `type` (`all|semantic|episodic|belief|goal`, default `all`)
  - `limit` (number, default `5`)
  - `min_relevance` (number, default `0.6`)
- Behavior: checks `/health` first, then retrieves via `/retrieve` and returns formatted memory results.

2. `memory_commit`
- Purpose: explicitly persist important facts/decisions/beliefs/goals.
- Input:
  - `content` (string, required)
  - `type` (`semantic|episodic|belief|goal`, required)
  - `importance` (1-10, default `5`)
  - `tags` (string array, optional)
- Behavior:
  - checks `/health` first
  - auto-tags if missing (`working_question`, `decision` heuristics)
  - commits are serialized (sequential) to protect local CPU embedding throughput
  - if server is unreachable, payload is queued to `.memory_retry_queue.json`
  - unreachable response is explicit:
    - `Memory commit failed - server unreachable. Queued for retry.`

3. `...

# Smart Memory v2 - Cognitive Architecture for OpenClaw

<p>
  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white">
  <img alt="Python" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white">
  <img alt="FastAPI" src="https://img.shields.io/badge/FastAPI-Persistent%20Local%20API-009688?logo=fastapi&logoColor=white">
  <img alt="Embeddings" src="https://img.shields.io/badge/Embeddings-nomic--embed--text--v1.5-blue">
  <img alt="PyTorch" src="https://img.shields.io/badge/PyTorch-CPU--Only-critical?logo=pytorch">
  <img alt="License" src="https://img.shields.io/badge/License-MIT-black">
</p>

> **Not a basic RAG cache.**  
> Smart Memory v2 is a persistent, local cognitive engine for OpenClaw with schema-versioned long-term memory, hot working memory, background cognition, strict token-bounded prompt composition, and a continuously running FastAPI process.

---

## Quick Value (60 seconds)

| You Need | Smart Memory v2 Gives You |
|---|---|
| Continuity across sessions | Typed long-term memory (`episodic`, `semantic`, `belief`, `goal`) |
| Fast local recall | Nomic embeddings + vector search + reranking |
| Stable context quality | Strict prompt token enforcement with deterministic eviction priority |
| Better long-run memory quality | Semantic dedup, reinforcement, consolidation, decay, and conflict resolution |
| Lightweight installs | CPU-only PyTorch standard (no CUDA wheel bloat) |
| Operational visibility | `/health`, `/memories`, `/memory/{id}`, `/insights/pending` |

---

## Why This Exists

Most memory plugins are retrieval wrappers. They do not behave like cognition.  
Smart Memory v2 is designed as a **cognitive pipeline**:

- `Ingestion`: Decide what is memory-worthy.
- `Retrieval`: Find relevant memories with entity and time bias.
- `Working Memory`: Keep a small, high-signal mind state.
- `Background Cognition`: Reflect, consolidate, decay, and resolve conflicts.
- `Prompt C...