Moneta Memory Mcp

Writing Good Recall Queries

• Formulate queries as natural-language questions or topic phrases.
• Be specific enough to surface relevant results, but not so narrow that you miss related memories.
• Use scope filters to narrow results when you know the context:
  • scope.repo -- limit to a specific repository
  • scope.tags -- filter by tags like ["convention"] or ["bug-fix"]
  • scope.agent -- limit to a specific agent's memories
  • scope.engineer -- limit to a specific engineer's agents

When to Remember

You should proactively save memories whenever you learn something that would help a future agent working on this project. Do not wait to be asked. If you find yourself thinking "I wish I had known this earlier," that is a memory worth saving.

Remember in these situations:

• After discovering a codebase convention or pattern. Example: "All API route handlers in this project use zod validation middleware before the controller function."

• When the user states a preference or gives corrective feedback. Example: "User preference: always use named exports, never default exports."

• After making an architectural decision -- save the rationale, not just the choice. Example: "Chose Redis for session storage over JWT because sessions need server-side revocation for the admin panel."

• After fixing a bug -- save what was wrong and why. Example: "The auth token cache in AuthService was shared across requests because it was a module-level variable. Fixed by moving it into the request context."

• When learning about tooling, deployment, or environment specifics. Example: "CI runs on GitHub Actions. The test suite requires a running PostgreSQL instance -- use the docker-compose.ci.yml service."

• After completing a task -- save key learnings that would help a future agent.

How to Write Good Memories

• Self-contained. A future agent with zero context should understand the fact without needing to read the conversation that produced it.
• Concise. One clear statement per memory. Keep it under 2000 characters. If you have multiple facts, store multiple memories.
• Factual. State what IS, not what was discussed. Write assertions, not narratives.
• Not code. Do not dump code blocks, conversation logs, or full documents into memories. Summarize the insight instead.

Bad memory: "We talked about auth and decided to change it." Good memory: "Authentication uses short-lived JWTs (15 min) with a refresh token rotation strategy. The refresh endpoint is POST /api/auth/refresh."

Tags

Use tags to categorize memories for easier retrieval. Common tags:

• convention -- coding standards, naming patterns, file organization rules
• architecture -- system design decisions and their rationale
• bug-fix -- root causes and solutions for bugs encountered
• preference -- user or team preferences for how things should be done
• tooling -- build tools, CI/CD, deployment, dev environment details
• gotcha -- non-obvious pitfalls or surprising behaviors

Importance Levels

• normal (default) -- standard memories, archived after 30 days of inactivity
• high -- important conventions or decisions that should persist longer
• critical -- fundamental project facts that must never be archived (auto-pinned)

Use critical sparingly -- reserve it for facts like "This project uses PostgreSQL 16 with pgvector" or "All API responses must follow the JSON:API envelope format."

The repo Field

Set the repo parameter when a memory is specific to a particular repository in a multi-repo project. Omit it when the memory applies to the whole project.

Tool Reference

remember -- Store a new memory

Near-duplicate memories from the same agent are automatically updated in place. If a different agent stores a near-duplicate, a new memory is created with a corroborated tag.

recall -- Search memories

Returns memories ranked by semantic similarity with scores, author info, and metadata.

correct -- Update a stale or wrong memory

Use correct when you find a memory that is outdated or inaccurate. The original author attribution is preserved.

forget -- Permanently delete a memory

Use forget when a memory is wrong and cannot be corrected, or is no longer relevant. This is permanent.

pin -- Protect a memory from archival

Pinned memories are never archived by the automatic archival process.

unpin -- Allow a memory to be archived

The memory is not immediately archived -- it simply becomes eligible for archival if not accessed within the archival window (default 30 days).

Example Workflow

Here is how to use Moneta during a typical task:

1. Recall before starting work:

User asks: "Add rate limiting to the API endpoints."

Before writing any code, recall relevant context:

• recall("How are API endpoints structured in this project?")
• recall("Are there any existing rate limiting patterns or middleware?")
• recall("What conventions does this project follow for middleware?")

2. Do the work using insights from recalled memories.

3. Remember what you learned:

After implementing the feature:

• remember("Rate limiting is implemented using express-rate-limit middleware in src/middleware/rateLimit.ts. The default limit is 100 requests per 15-minute window per IP.", tags: ["architecture", "convention"], importance: "high")

4. Correct stale memories if any recalled memories turned out to be outdated:

• correct(memory_id: "abc-123", new_content: "API middleware chain order: cors -> rateLimit -> auth -> validation -> handler (rate limiting was added before auth).")