Memory Aegis V5.0

Local, offline cognitive memory engine. Extracts structured claims (Subject-Predicate-Object) from conversation text, scores them on Intensity/Confidence/Salience, stores in SQLite with vector embeddings, and retrieves via hybrid semantic+keyword search with scope gating. Now with Procedural Memory — stores multi-step procedures with triggers, tracks success/failure, and suggests actions on recall.

When to use

• You need to remember facts from a conversation (names, preferences, relationships)
• You need to recall context relevant to a user query before generating a response
• You want long-term memory that persists across sessions
• You need a fully offline memory backend (no API calls, no cloud)
• You need scope isolation between projects (no cross-contamination)
• You need conflict detection when new facts contradict existing knowledge
• You need to store procedures/workflows that can be triggered and refined over time
• You need action suggestions — when a recall matches a known procedure, it suggests steps

Commands

Extract — store knowledge from a message

python3 scripts/memory_manager.py extract "Boss thích uống cà phê sữa đá ở Sài Gòn"

Input: Any user message (Vietnamese or English).
Output: JSON with extracted units (Subject-Predicate-Object triples with I/C/S scores).
What it does: Parses the message, scores Intensity/Confidence/Salience, detects conflicts, embeds, stores in SQLite.

Recall — retrieve relevant context

python3 scripts/memory_manager.py recall "Boss thích gì?" --scope=skyclaw

Input: A query string. Optional --scope=xxx for project isolation, --at=2026-01-15T12:00:00 for temporal queries.
Output: Formatted context with top-K results ranked by hybrid priority score. Supports --json.

Explain — audit a memory's provenance

python3 scripts/memory_manager.py explain <unit_id>

Resolve — manually resolve a conflict

python3 scripts/memory_manager.py resolve <unit_id> accept|reject|keep_both

Idle — run full background maintenance

python3 scripts/memory_manager.py idle

Runs: consolidation (RAW->STABLE->GOLDEN_RULE) + clustering + link prediction + decay.

Decay — forget weak memories

python3 scripts/memory_manager.py decay

Consolidate — promote reinforced memories

python3 scripts/memory_manager.py consolidate

Stats — database overview

python3 scripts/memory_manager.py stats
python3 scripts/memory_manager.py stats --json

Search — BM25-only keyword search

python3 scripts/memory_manager.py search "cà phê"

Export — dump all units as JSON

python3 scripts/memory_manager.py export
python3 scripts/memory_manager.py export backup.json

Import — load units from JSON file

python3 scripts/memory_manager.py import backup.json

Procedure-Add — store a multi-step procedure

python3 scripts/memory_manager.py procedure-add "khi Boss nói dịch" "Mở file nguồn | Dịch nội dung | Lưu kết quả"
python3 scripts/memory_manager.py procedure-add "deploy to prod" "pull code | build | run tests | deploy" --scope=skyclaw

Input: A trigger pattern + steps separated by |. Optional --scope=xxx.
Output: Created procedure ID with step count.

Procedure-List — list stored procedures

python3 scripts/memory_manager.py procedure-list
python3 scripts/memory_manager.py procedure-list --scope=skyclaw --status=STABLE --json

Feedback — record success/failure for a procedure

python3 scripts/memory_manager.py feedback <unit_id> success
python3 scripts/memory_manager.py feedback <unit_id> failure

What it does: Increments success/failure counters, adjusts confidence. Procedures that accumulate enough successes get promoted (RAW→STABLE at 3, STABLE→GOLDEN_RULE at 8 with confidence ≥ 0.85 and failure < 30%).

Action Loop (automatic)

When you recall a query and the result matches a stored procedure, the output includes:

• [ACTION] tag in the result line
• Procedure steps with their order and dependencies
• Success rate based on feedback history

Dependencies

Package	Required	Purpose	Fallback
pydantic	yes	Input validation	none — will not start
sentence-transformers	yes	Local embedding (paraphrase-multilingual-MiniLM-L12-v2)	none — will not start
sqlite-vss	no	Fast vector search via SQLite extension	Brute-force cosine (works, slower at scale)

Install

pip install sentence-transformers pydantic
# Optional: pip install sqlite-vss

Configuration

export OPENCLAW_MEMORY_DB="/path/to/memory.db"    # Database path (default: ./data/openclaw_memory_v3.db)

Architecture

• Storage: SQLite with memory_units + memory_clusters + memory_edges + procedure_meta + procedure_steps tables
• Vector index: sqlite-vss virtual table (384-dim), with brute-force cosine fallback
• Embeddings: sentence-transformers paraphrase-multilingual-MiniLM-L12-v2, loaded once, CPU-only
• Extraction: Rule-based regex (EN + VI) with Vietnamese entity normalization + embedding-based entity resolution
• Scoring: Tri-Axis (Intensity, Confidence, Salience) + Cognitive Decay Formula
• Retrieval: Hybrid Vector + BM25 with Scope Gating + Temporal Filter + Conflict Penalty
• Memory Hierarchy: 5-Tier (-1 Constitution, 0 Identity, 1 Semantic, 2 Episodic, 3 Working)
• Consolidation: RAW -> STABLE (reinforcement >= 3) -> GOLDEN_RULE (reinforcement >= 10 + confidence >= 0.9)
• Conflict Resolution: SUPERSEDES (auto-deprecate), EXCEPTION_TO (edge creation), HARD_CONFLICT (candidate + user review)
• Procedural Memory: Stores multi-step procedures with trigger patterns, preconditions, and success/failure tracking
• Action Loop: Recall automatically suggests procedure steps when matching a stored procedure
• Procedure Consolidation: RAW → STABLE (3 successes) → GOLDEN_RULE (8 successes + confidence ≥ 0.85 + failure < 30%)

Security

• No network calls — no requests, urllib, or any HTTP library. All models load from local disk
• Pydantic validation — all inputs validated via strict Pydantic models
• Parameterized SQL — 100% ? placeholders, zero string interpolation
• Path traversal protection — rejects paths containing .. components

Limitations

• Rule-based extraction only handles simple sentence patterns (subject-verb-object)
• paraphrase-multilingual-MiniLM-L12-v2 has moderate Vietnamese support
• Entity resolution via embedding similarity requires stored entities to compare against