MnemoQ
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MnemoQ log learning about JWT token expiry handling"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 mnemoqRelated MCP server: Cortex
Quick 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)
mnemoq --install-hooks # Install git post-commit auto-learn hookFor the full retrieve → work → log → evaluate → auto-learn loop and how to wire it into any IDE or agent, see the Integration Guide.
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 |
| Log, retrieve, consolidate, and manage agent memories |
| Initialize a new project with memory directory and config |
| Update engine files in existing projects |
| Start MCP server (JSON-RPC over stdio) |
| 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 identifier |
|
| Minimum engine version |
|
| Config schema version |
|
| Cap on step values ( |
|
| Accepted domain whitelist |
|
| Accepted agent whitelist |
|
| Agents that can retrieve but not log |
|
| Custom domain → canonical tag mappings |
|
| HTTP API auth key ( |
|
| sentence-transformers model name |
|
| Model file cache path |
|
| Reranker mode: |
|
| Number of top results to rerank |
|
| Cross-encoder model name |
|
| LLM endpoint URL for |
|
| LLM model name for |
|
| Exponential decay per step (recency) |
|
| Minimum score for non-critical candidates |
|
| Weight when task components match |
|
| Weight when task files match |
|
| Weight when domain matches |
|
| Weight when nothing matches |
|
| Max critical entries per retrieval |
|
| Max non-critical entries per retrieval |
|
| Step window for minor entries |
|
| Step window for major entries |
|
| Step age for escalation flagging |
|
| BM25 term frequency saturation |
|
| BM25 document length normalization |
|
| Reciprocal rank fusion constant |
|
| Blend weight: |
|
| Cosine similarity for duplicate detection |
|
| Days between consolidation triggers |
|
| Quarantine count that triggers consolidation |
Data Schema
Each entry in learnings.jsonl is a JSON object with these required fields:
Field | Type | Constraint |
|
| ≥ 1 |
|
| must be a valid agent name |
|
|
|
|
| e.g. |
|
| non-empty |
|
| non-empty |
|
| must start with |
|
| must contain |
|
| non-empty |
|
| 1–10 |
|
|
|
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/mnemoq/— Engine source (CLI, retrieval, validation, consolidation, MCP server, dashboard, SDK)src/mnemoq/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.
Available Tools
8 toolscapture_interactionA
Capture a conversation interaction as memory. Extracts learnable moments from raw text and auto-logs them. Three-tier extraction: online LLM, offline LLM, heuristic fallback.
Inputs: conversation (required), step.
consolidateB
Trigger a Sleep Cycle (consolidation): archives unresolved entries, generates promotion candidates, detects contradictions, and checks for stale entries.
Inputs: force, sprint_number.
evaluate_promptB
Evaluate a structured prompt summary for learnable moments. Runs heuristic detectors on the summary, auto-logs high-confidence signals, and returns suggestions for medium-confidence ones.
Inputs: step (required), outcome (required), components (required), prompt_type (required), +5 more.
get_statsA
Get memory system statistics: total entries, unresolved/resolved counts, severity/type/scope breakdowns, reinforcement patterns, and sleep cycle status.
Inputs: no named parameters.
log_learningA
Log a new learning entry. Validates, checks for duplicates/semantic duplicates, and appends to memory. Returns status (added/duplicate/semantic_duplicate/conflict/quarantined) and entry details.
Inputs: entry (required).
resolve_learningB
Mark an existing learning entry as resolved by its timestamp.
Inputs: timestamp (required).
retrieve_learningsA
Retrieve relevant learnings for the current task context. Returns warnings (critical issues) and patterns (architectural guidance), scored and ranked by relevance.
Inputs: step (required), files, domain, components.
review_agentsB
Diagnostic report on AGENTS.md section health. Cross-references recent learnings with AGENTS.md sections, categorizing sections as active (referenced by learnings), cold (no references), and identifying unmatched learnings.
Inputs: step (required), threshold.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: capturing raw interactions, logging structured learning, evaluating prompts, retrieving relevant learnings, resolving entries, consolidating memory, and reviewing agent documentation. No two tools overlap in function.
Most tools follow a clear verb_noun pattern in snake_case (e.g., capture_interaction, log_learning, retrieve_learnings). However, 'consolidate' breaks the pattern as a single verb without a noun, causing a minor inconsistency.
With 8 tools, the server covers core memory operations (create, read, update, consolidate, evaluate) without being overwhelming. The count is well-scoped for a memory management system.
The server lacks direct update and delete operations for learning entries, which are common in memory systems. While resolve_learning provides status change, editing entry content is missing. Retrieval is limited to context-based relevance, missing full listing.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal-first memory engine that synthesizes entity profiles at ingestion. Enables persistent, reasoning memory for AI agents via MCP tools like add, search, and profile.MIT
- AlicenseNot gradedqualityDmaintenanceLocal-first AI memory layer with hybrid retrieval and brain-inspired namespaces. Enables agents to save, search, and manage memories directly via MCP tools.MIT
- AlicenseNot gradedqualityFmaintenanceLocal-first, auditable memory for AI agents. Provides durable context for MCP hosts with SQLite storage, CLI, and MCP tools for memory management.2Apache 2.0
- AlicenseCqualityAmaintenanceProvides AI agents with a human-inspired memory layer via MCP, enabling episodic and semantic memory recall, forgetting curves, consolidation, and contradiction detection. It integrates with MCP clients to offer local-first, dependency-free memory management.981MIT