功能描述

Searches, stores, and manages agent memory across 4 sources (fact store, vector embeddings, BM25, knowledge graph). Runs 100% local via Ollama — no API keys,...

使用说明 (SKILL.md)

Agent Memory Tools

Name: Agent Memory Tools
Author: primo-studio

Multi-source memory recall and fact management. Runs locally via Ollama (0€).

Architecture

Question → unified_recall.py → fan-out 4 sources → merge → score → rerank → answer
                                 ├─ Fact store (Convex or local JSON)
                                 ├─ Vector embeddings (nomic)
                                 ├─ BM25 full-text (QMD)
                                 └─ Knowledge graph (JSON)

File changed → auto_ingest.py → extract facts → contradiction check → store
                               → update embeddings → rebuild graph

Setup

# Install Ollama models (one-time)
ollama pull gemma3:4b              # LLM (~2s/call)
ollama pull nomic-embed-text-v2-moe  # Embeddings

# Verify everything works
python3 scripts/selftest.py

Requirements: Python 3.9+, Ollama, curl. Optional: QMD CLI (bun install -g qmd).

Core Scripts

Search memory

# Unified recall — recommended (all 4 sources, scored + reranked)
python3 scripts/unified_recall.py "What bugs happened last week?" --debug

# Multi-hop reasoning (chains searches with LLM synthesis)
python3 scripts/multihop_search.py "How does the deploy pipeline work?" --embed

# Temporal decay (recent facts score higher, errors protected)
python3 scripts/decay_search.py "recent issues" --half-life 14

Extract and store facts

# Extract from text
python3 scripts/extract_facts.py "Some conversation or document" --store --debug

# Extract from file
python3 scripts/extract_facts.py --file path/to/doc.md --store

# Pipe from stdin
cat summary.md | python3 scripts/extract_facts.py --store

Facts are checked for contradictions locally (gemma3, ~2s) before storage. Categories: knowledge, error, timeline, preference, tool, client, hr.

Auto-ingest workspace changes

python3 scripts/auto_ingest.py --scan          # One-shot: process modified .md files
python3 scripts/auto_ingest.py --watch          # Daemon: poll for changes every 30s
python3 scripts/auto_ingest.py --file doc.md    # Single file

Dedup by content hash + 5 min cooldown. Triggers: fact extraction → storage → embed cache update → graph rebuild.

Build knowledge graph

python3 scripts/knowledge_graph.py              # Full rebuild
python3 scripts/knowledge_graph.py --dry-run    # Preview without writing

Graph stored at .cache/knowledge-graph.json. Auto-rebuilt incrementally by auto_ingest.py.

Run tests

python3 scripts/tests.py    # 28 unit tests

Configuration

Edit scripts/config.json. See references/configuration.md for full guide.

Storage backend — auto-detected:

convexUrl set → uses Convex (agentMemory API)
No convexUrl → uses local .cache/agent-facts.json

Model presets — switch LLM/embeddings provider in one flag:

python3 scripts/unified_recall.py "query" --preset ollama      # Default
python3 scripts/unified_recall.py "query" --preset lmstudio
python3 scripts/unified_recall.py "query" --preset openai

Per-script model override — in config.json → scriptOverrides:

"scriptOverrides": {
  "recall":  { "llm": { "model": "gemma3:4b", "apiFormat": "ollama" } },
  "extract": { "llm": { "model": "gemma3:4b", "apiFormat": "ollama" } }
}

Recommended models by RAM:

RAM	LLM	Embeddings
4 GB	gemma3:1b	nomic-embed-text
8 GB	gemma3:4b ✓	nomic-embed-text-v2-moe
16+ GB	qwen3.5:27b	nomic-embed-text-v2-moe

⚠ Avoid Qwen 3.5 for JSON tasks — outputs to "thinking" field instead of response.

Platform auto-trigger

Platform	Method
macOS	LaunchAgent with WatchPaths
Linux	systemd timer or cron
Windows	Task Scheduler

See references/configuration.md for examples.

File Structure

scripts/
├── unified_recall.py      # Multi-source search + scoring + synthesis
├── extract_facts.py       # Fact extraction + contradiction check + storage
├── auto_ingest.py         # File watcher / scanner pipeline
├── multihop_search.py     # Chained reasoning search
├── decay_search.py        # Time-weighted search
├── knowledge_graph.py     # Entity/relationship graph builder
├── fact_store.py          # Storage abstraction (Convex / local JSON)
├── llm_client.py          # LLM/embedding client (Ollama/LM Studio/OpenAI)
├── selftest.py            # Setup validation
├── tests.py               # Unit tests (28)
└── config.json            # Configuration + presets
references/
└── configuration.md       # Full configuration guide

安全使用建议

This package appears to do what it says: it reads markdown in a configured workspace, extracts facts with a local LLM (Ollama) by default, stores them in local JSON, updates embeddings, and can rebuild a knowledge graph. Before installing or running it: 1) Set MEMORY_WORKSPACE or scripts/config.json paths to a directory that contains only files you want the tool to read; otherwise the watcher may scan large or sensitive folders. 2) Review scripts/config.json: Convex (convexUrl) and API presets (openai/openrouter) are optional but will send data to remote services if enabled—do not supply secrets or endpoints you don't trust. 3) setup.sh will attempt to install/run Ollama (it uses the official ollama.com installer and runs ollama pull for models). 4) If you enable auto-ingest as a system service (LaunchAgent/systemd/Task Scheduler), be aware it will run periodically and process changed files. 5) If you want to avoid any network transmission, stick with the default Ollama preset and local JSON backend and do not set convexUrl or API keys. Overall, the skill is coherent with its stated purpose; the main risk is accidental data transmission if you switch to remote presets or configure a remote convexUrl—review configuration before use.

功能分析

Type: OpenClaw Skill Name: agent-memory-tools Version: 1.0.0 The agent-memory-tools bundle is a comprehensive local memory management system for AI agents, utilizing Ollama for LLM and embedding tasks. The code implements multi-source retrieval (Vector, BM25, Knowledge Graph, and Fact Store), auto-ingestion of workspace changes, and temporal decay scoring. All network activity is directed to user-configured LLM endpoints (defaulting to localhost:11434) or an optional Convex backend. The setup script follows standard practices for installing Ollama, and the Python scripts use subprocess calls to curl for API interactions to minimize external dependencies. No evidence of data exfiltration, malicious persistence, or prompt injection was found; the logic is consistent with the stated purpose of providing a private, local-first memory layer.

能力评估

✓ Purpose & Capability

Name/description match the implementation: scripts provide fact extraction, multi-source recall (fact store, embeddings, BM25, graph), auto-ingest, and local-only operation via Ollama by default. No unexpected binaries or credentials are required for the default local flow.

ℹ Instruction Scope

SKILL.md instructs the agent to read markdown files in a workspace, extract facts, update embeddings, and optionally run watchers/daemons. That behavior matches the stated purpose. Note: the auto-ingest and graph-builder will read any files under the configured workspace paths (default watch dirs include memory, agents, projects, docs, notes); make sure the configured workspace is limited to the intended files.

✓ Install Mechanism

There is no complex install spec in the registry; the included setup.sh uses official Ollama model pulls and (on Linux) the official https://ollama.com/install.sh script. Model pulls (ollama pull ...) are expected for a local LLM workflow. No obscure download hosts or URL shorteners are used.

ℹ Credentials

The skill declares no required env vars and defaults to local Ollama. However configs/presets explicitly support OpenAI/OpenRouter and a Convex backend: if a user enables those presets or sets convexUrl, the code will POST facts to that endpoint (fact_store uses curl subprocesses) or call remote APIs. These remote credentials are optional but powerful—ensure you only supply API keys/convexUrl to trusted endpoints and understand that stored facts may be transmitted when those backends are selected.

ℹ Persistence & Privilege

The skill does not request always:true and does not auto-register itself. It documents how to run auto_ingest as a daemon (LaunchAgent/systemd/Task Scheduler) but will not enable that automatically. If you follow those guides, the watcher will run periodically and re-ingest files in the configured workspace.

版本历史

v1.0.0

agent-memory-tools 1.0.0 — first release - Search, store, and manage workspace knowledge across four local sources: fact store (Convex/JSON), vector embeddings, BM25 full-text, and knowledge graph. - 100% local operation via Ollama; no API keys or cloud dependency required. - Includes unified search, multi-hop reasoning, fact extraction with contradiction checks, auto-ingest from file changes, and knowledge graph building. - Modular Python scripts for recall, extraction, ingestion, time-weighted search, and entity graph management. - Flexible configuration for storage backend, LLM, and embeddings provider. - Designed for privacy, extensibility, and easy local setup.

元数据

Slug agent-memory-tools

版本 1.0.0

许可证 MIT-0

累计安装 1

当前安装数 1

历史版本数 1

常见问题