Smart Memory

Persistent local cognitive memory for OpenClaw via a Node adapter and FastAPI engine.

Security Scan

The skill largely implements a local cognitive memory system that matches its description, but it includes prompt-injection style guidance (modify the agent base prompt), recommends changing OpenClaw config, and bundles an install/start flow that writes into your home workspace — these behaviors expand the skill's influence beyond simple memory storage and warrant caution.

Purpose & Capability

The name/description (local cognitive memory via Node adapter + FastAPI) match the included code: Node adapter, FastAPI server, ingestion/retrieval/prompt composition, hot-memory persistence and background cognition. Files and APIs referenced are coherent with the stated purpose.

Instruction Scope

SKILL.md and integration docs instruct agents to (a) inject a standardized `[ACTIVE CONTEXT]` block into the agent base prompt and add a guidance line to the agent's base/system prompt, (b) adopt a mandatory startup priming sequence, and (c) disable OpenClaw's built-in memory tools via config changes. The passive context injection and the explicit recommendation to modify the agent's base prompt are effectively prompt-injection vectors that expand the skill's influence on agent behavior beyond API/tool calls. The skill also reads/writes files under $HOME/.openclaw/workspace and makes local HTTP calls to 127.0.0.1:8000 — these are expected for local memory but are part of the runtime surface the agent will interact with.

Install Mechanism

No formal registry install spec was declared, but the repository includes install.sh and a Node postinstall that creates Python venv and installs CPU PyTorch wheels. The installer clones the GitHub repo (BluePointDigital/smart-memory) and runs npm install which triggers local venv setup and pip installs. These are standard but the lack of a declared install spec in the registry means the installer runs only if the user executes it — inspect postinstall.js and install.sh before running. All network references appear to be GitHub or PyTorch official index URLs, not arbitrary/personal servers.

Credentials

The skill requests no environment variables or external credentials and operates on local resources. It persists hot-memory and other runtime files under the user's OpenClaw workspace (~/.openclaw/workspace/smart-memory and similar). This filesystem access is proportionate to a local memory service, but it does create and modify files in the user's home workspace and will create a virtualenv and pip-installed packages if you run install steps.

Persistence & Privilege

The skill does not set always:true and does not require elevated platform privileges. It does, however, ask integrators to modify OpenClaw configuration (disable built-in memory tools) and to add lines to the agent base prompt — both are persistent changes to agent behavior/config that are outside the skill's own runtime files. Those suggested config/prompt changes can have system-wide effects and should be applied consciously.

Scan Findings in Context

[system-prompt-override] unexpected: SKILL.md includes passive context injection and instructs adding a guidance line to the agent base prompt; while injecting contextual blocks is part of the memory feature, recommending edits to the agent base/system prompt is a prompt-injection pattern and could be abused to alter agent behavior beyond the memory tool.

What to consider before installing

This repository appears to implement the memory service it claims, but it asks you to: (1) run an installer that will clone code into your OpenClaw workspace and create a Python venv / install CPU PyTorch wheels, (2) write persistent files under your home workspace (~/.openclaw/...), and (3) change your agent's base prompt and OpenClaw config (disabling built-in memory tools). Before installing: review postinstall.js and install.sh to see exactly what they do; inspect the SKILL.md/skills/smart-memory-v25 prompt-injection code to understand what will be injected into your agent prompts; consider running the service in an isolated workspace or container first; back up your OpenClaw configuration before applying the suggested config changes; and avoid blindly applying the recommended base-prompt modification — instead, manually review and decide whether to incorporate those lines. If you want a lower blast radius, run the service locally in a container or VM and only enable the skill after manual inspection of postinstall hooks and the prompt-injection helper code.

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. memory_insights

• Purpose: surface pending background insights.
• Input:
  • limit (number, default 10)
• Behavior: checks /health first, calls /insights/pending, returns formatted insight list.

Reliability Guarantees

• Mandatory health gate before each tool call (GET /health).
• Retry queue flushes automatically on healthy tool calls and heartbeat.
• Heartbeat supports automatic retry recovery and background maintenance.

Session Arc Lifecycle Hooks

The v2.5 skill supports episodic session arc capture:

• checkpoint capture every 20 turns
• session-end capture during teardown/reset

Flow:

1. Extract recent conversation turns (up to 20).
2. Run summarization with prompt:
   • Summarize this session arc: What was the goal? What approaches were tried? What decisions were made? What remains open?
3. Persist summary through internal memory_commit as:
   • type: "episodic"
   • tags: ["session_arc", "YYYY-MM-DD"]

Passive Context Injection

Use inject_active_context (or createOpenClawHooks().beforeModelResponse) before response generation.

This adds the standardized block:

[ACTIVE CONTEXT]
Status: {status}
Active Projects: {active_projects}
Working Questions: {working_questions}
Top of Mind: {top_of_mind}

Pending Insights:
- {insight_1}
- {insight_2}
[/ACTIVE CONTEXT]

Add this guidance line to your agent base prompt:

If pending insights appear in your context that relate to the current conversation, surface them naturally to the user. Do not force it - but if there is a genuine connection, seamlessly bring it up.

Minimal OpenClaw Wiring Example

const {
  createSmartMemorySkill,
  createOpenClawHooks,
} = require("./skills/smart-memory-v25");

const memory = createSmartMemorySkill({
  baseUrl: "http://127.0.0.1:8000",
  summarizeSessionArc: async ({ prompt, conversationText }) => {
    return openclaw.llm.complete({ system: prompt, user: conversationText });
  },
});

const hooks = createOpenClawHooks({
  skill: memory.skill,
  agentIdentity: "OpenClaw Agent",
  summarizeWithLLM: async ({ prompt, conversationText }) => {
    return openclaw.llm.complete({ system: prompt, user: conversationText });
  },
});

// Register memory.tools as callable tools:
// - memory_search
// - memory_commit
// - memory_insights
// and call hooks.beforeModelResponse / hooks.onTurn / hooks.onSessionEnd at lifecycle points.

Node Adapter Methods (Base Adapter)

• start() / init()
• ingestMessage(interaction)
• retrieveContext({ user_message, conversation_history })
• getPromptContext(promptComposerRequest)
• runBackground(scheduled)
• stop()

API Endpoints

• GET /health
• POST /ingest
• POST /retrieve
• POST /compose
• POST /run_background
• GET /memories
• GET /memory/{memory_id}
• GET /insights/pending

Install (CPU-Only Required)

For Docker, WSL, and laptops without NVIDIA GPUs, use CPU-only PyTorch.

# from repository root
cd smart-memory

# Create Python venv
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install CPU-only PyTorch FIRST
pip install torch --index-url https://download.pytorch.org/whl/cpu

# Then install remaining dependencies
pip install -r requirements-cognitive.txt

# Finally, install Node dependencies
npm install

PyTorch Policy

• Smart Memory v2 supports CPU-only PyTorch only.
• Do not install GPU/CUDA PyTorch builds for this project.
• Use the bundled installer flow (npm install -> postinstall.js) so CPU wheels are always used.

Deprecated

Legacy vector-memory CLI artifacts (smart_memory.js, vector_memory_local.js, focus_agent.js) are removed in v2.