Findings & checks · 2 flagged
MEDIUMInstruction telling the agent not to ask for approvalSS-SKILL-INJECT-DONT-ASK-01 · Prompt injection · .windsurf/workflows/plan-reviewer.md
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
- Delete blanket "don't ask / no need to confirm" directives from the skill.
- If the skill is a genuine autonomous job, restrict the opt-out to a named non-destructive action rather than all actions.
Trace & refs
MEDIUMInstruction telling the agent not to ask for approvalSS-SKILL-INJECT-DONT-ASK-01 · Prompt injection · templates/windsurf/workflows/plan-reviewer.md
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
- Delete blanket "don't ask / no need to confirm" directives from the skill.
- If the skill is a genuine autonomous job, restrict the opt-out to a named non-destructive action rather than all actions.
Trace & refs
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
MnemoQ
Local-first memory engine for AI agents — MCP-native, graph-linked, spaced repetition.
Agent ──log──▶ MnemoQ Engine ──store──▶ learnings.jsonl
Agent ◀──retrieve── MnemoQ Engine ◀──read── learnings.jsonl
Agent ──MCP──▶ mnemoq-mcp ──read/write──▶ learnings.jsonl
Install
pip install mnemoqCLI-only users (no Python project needed):
pipx install mnemoqQuick Start
1. Scaffold a project
mnemoq-scaffold ./my-project --defaultsThis creates a memory/ directory with config.json and learnings.jsonl in your project.
Wire memory into your IDE/agent platform:
mnemoq-scaffold ./my-project --defaults --ide windsurf
mnemoq-scaffold ./my-project --defaults --ide windsurf,cursor,claude-code
mnemoq-scaffold ./my-project --defaults --ide all
mnemoq-scaffold --ide ?Supported platforms: opencode, windsurf, cursor, claude-code, copilot, all.
2. Log a learning
mnemoq --log '{"step":3,"source_agent":"claude","type":"pattern","domain":"backend","components":["api","auth"],"files_touched":["src/auth.py"],"trigger":"JWT validation failed on expired tokens","action":"Added explicit expiry check before signature verification","reason":"PyJWT silently accepts expired tokens when verify_exp is not set","importance":8,"severity":"major"}'PowerShell-safe alternative (avoids JSON quoting issues):
mnemoq --log-file learning.json3. Retrieve relevant learnings
mnemoq --step 3 --components api,auth --domain backend4. Other commands
mnemoq --stats # Memory statistics
mnemoq --resolve 2025-06-25T10:30:00 # Mark a learning resolved
mnemoq --review-agents --step 3 # AGENTS.md section health report
mnemoq --consolidate # Archive + promote (sleep cycle)5. MCP server
MCP is the primary integration path for AI agents. The server runs over stdio (JSON-RPC 2.0) with no HTTP dependency.
mnemoq-mcp # auto-discovers memory/ in cwd
mnemoq-mcp --memory-dir /path/to/memory # explicit pathOr via environment variable: AGENT_MEMORY_DIR=/path/to/memory mnemoq-mcp
Tools exposed: retrieve_learnings, log_learning, resolve_learning, get_stats, consolidate
Works with Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible client. See the full MCP integration guide for client configuration snippets, tool reference, and troubleshooting.
CLI Reference
| Command | Description |
|---|---|
mnemoq | Log, retrieve, consolidate, and manage agent memories |
mnemoq-scaffold | Initialize a new project with memory directory and config |
mnemoq-update | Update engine files in existing projects |
mnemoq-mcp | Start MCP server (JSON-RPC over stdio) |
scripts/generate_fakes.py | Generate synthetic memory entries for testing |
See docs/cli-reference.md for all flags, examples, and mutual-exclusion rules.
Configuration
memory/config.json tunes retrieval scoring, retention, embeddings, reranking, and access control for your project. Below is a summary of all parameters — see the full Config Tuning Guide for ranges, defaults, and tuning recipes.
| Parameter | Default | What it controls |
|---|---|---|
project_name | "<PROJECT_NAME>" | Project identifier |
engine_min_version | "1.15.0" | Minimum engine version |
schema_version | 1 | Config schema version |
max_step | null | Cap on step values (null = no cap) |
valid_domains | null | Accepted domain whitelist |
valid_source_agents | null | Accepted agent whitelist |
retrieval_only_agents | null | Agents that can retrieve but not log |
domain_mappings | null | Custom domain → canonical tag mappings |
api_key | null | HTTP API auth key (null = no auth) |
embedding_model | "all-MiniLM-L6-v2" | sentence-transformers model name |
embedding_cache_dir | "~/.agent-memory/models/" | Model file cache path |
reranker | "none" | Reranker mode: none, cross-encoder, llm-local |
reranker_top_n | 20 | Number of top results to rerank |
reranker_model | "cross-encoder/ms-marco-MiniLM-L-12-v2" | Cross-encoder model name |
reranker_llm_endpoint | null | LLM endpoint URL for llm-local mode |
reranker_llm_model | null | LLM model name for llm-local mode |
tuning.decay_rate | 0.995 | Exponential decay per step (recency) |
tuning.score_threshold | 0.15 | Minimum score for non-critical candidates |
tuning.component_weight | 1.0 | Weight when task components match |
tuning.file_weight | 0.7 | Weight when task files match |
tuning.domain_weight | 0.4 | Weight when domain matches |
tuning.no_match_weight | 0.1 | Weight when nothing matches |
tuning.max_warnings | 5 | Max critical entries per retrieval |
tuning.max_patterns | 15 | Max non-critical entries per retrieval |
tuning.minor_retention | 5 | Step window for minor entries |
tuning.major_retention | 20 | Step window for major entries |
tuning.escalation_threshold | 30 | Step age for escalation flagging |
tuning.bm25_k1 | 1.5 | BM25 term frequency saturation |
tuning.bm25_b | 0.75 | BM25 document length normalization |
tuning.rrf_k | 60 | Reciprocal rank fusion constant |
tuning.embedding_alpha | 0.5 | Blend weight: alpha * rrf + (1-alpha) * cosine |
tuning.semantic_dedup_threshold | 0.85 | Cosine similarity for duplicate detection |
tuning.sleep_cycle_days | 7 | Days between consolidation triggers |
tuning.sleep_cycle_quarantine_threshold | 20 | Quarantine count that triggers consolidation |
Data Schema
Each entry in learnings.jsonl is a JSON object with these required fields:
| Field | Type | Constraint |
|---|---|---|
step | int | ≥ 1 |
source_agent | str | must be a valid agent name |
type | str | bug_fix, optimization, or architectural_pattern |
domain | str | e.g. backend, testing, security |
components | list[str] | non-empty |
files_touched | list[str] | non-empty |
trigger | str | must start with When |
action | str | must contain ALWAYS or NEVER |
reason | str | non-empty |
importance | int | 1–10 |
severity | str | minor, major, or critical |
The engine auto-stamps ts, commit, access_count, reinforcement_count, embedding, schema_version, and provenance fields at log time. See docs/data-schema.md for the full reference including optional fields, enum values, schema versioning, and sample entries.
Development
git clone https://github.com/Mnemoq/MnemoQ.git
cd MnemoQ
pip install -e ".[dev]"
pytestStructure
src/agent_memory/— Engine source (CLI, retrieval, validation, consolidation, MCP server, dashboard, SDK)src/agent_memory/engine/— Core modules (retrieval, scoring, reranking, consolidation, validation, server)tests/— Test suitetemplates/— Config templates, prompts, eval datadocs/— Architecture documentation (index)scripts/— Deploy scripts
Changelog
See CHANGELOG.md.
Roadmap
See docs/ROADMAP.md for current status and planned features.
License
AGPL-3.0-or-later. See LICENSE for details.
Contributing
See CONTRIBUTING.md. Submitting a PR constitutes acceptance of the CLA.
Security
Report vulnerabilities privately via GitHub Security Advisories. See SECURITY.md for details.