AutoGineer
Generated banner for memanto
Generated logo for memanto

memanto

Agent plugin

First committed by het0814

Published in moorcheh-ai/memanto. Publisher page

2,363 GitHub stars

What it is

Memory that AI Agents Love!
— the description by het0814

AutoGineer overview, from the brain’s own files

Memanto acts as a chief of staff for your AI agents, moving beyond simple storage to actively manage the lifecycle of agentic knowledge. Unlike passive vector stores, Memanto observes interaction streams to extract durable facts, decisions, and preferences. It handles the complex tasks of consolidating duplicate information, resolving contradictions between agents, and enforcing retention policies to prevent memory bloat. By providing a unified, portable estate that works across different frameworks and vendors, Memanto ensures that your agents remain consistent and informed without requiring manual intervention or complex application-level logic.

How it works

Memory model: Vector store

AutoGineer overview, from the brain’s own files

Memanto runs as a companion agent alongside your existing AI fleet. It uses a vector-store-based memory model to store knowledge, which it organizes into namespaces for different agents. It observes agent traffic to extract and categorize information, merges duplicates, and reconciles conflicting data points. Users can define retention policies in YAML files to automate the expiration of stale memories. The system provides a CLI for manual interaction, a REST API for integration, and supports exporting the entire memory estate into the Open Knowledge Format (OKF) for portability.

Folders
FolderRoleFiles
.githubagent-config7
assetsattachments11
docsdocs10
examplesexamples640
scriptsscripts1
teststests62
i18nfolder3
integrationsfolder105
memantofolder103
sdksfolder41

Requirements

Runtimes: Python >=3.10,<4

API keys (by name): MOORCHEH_API_KEY

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 4 hooks (claude-code), 3 scripts. Review examples/claudecode-skills-memanto/lifecycle-hooks/install.py, integrations/hermes-agents/hermes_memanto/install.py, memanto/cli/connect/assets/hooks/hooks.json, pyproject.toml before opening the folder in Claude Code. No step below turns a hook on for you.

    • examples/claudecode-skills-memanto/lifecycle-hooks/install.py: python examples/claudecode-skills-memanto/lifecycle-hooks/install.py
    • integrations/hermes-agents/hermes_memanto/install.py: python integrations/hermes-agents/hermes_memanto/install.py
    • memanto/cli/connect/assets/hooks/hooks.json: ${SYS_EXECUTABLE}
    • memanto/cli/connect/assets/hooks/hooks.json: ${SYS_EXECUTABLE}
    • memanto/cli/connect/assets/hooks/hooks.json: ${SYS_EXECUTABLE}
    • memanto/cli/connect/assets/hooks/hooks.json: ${SYS_EXECUTABLE}
    • pyproject.toml: hatch build hook vcs (hatch_build.py)
  2. Not scanned by AutoGineerIts dependencies are installed by pip or uv when you run it and were not scanned by AutoGineer (14 declared). https://pypi.org/project/memanto/

  3. First committed by het0814. Published in moorcheh-ai/memanto. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Automating memory curation across multiple agent frameworks
  • Resolving conflicting information between different agents
  • Enforcing data retention and expiration policies
  • Exporting agent memory to portable Markdown files
  • Bootstrapping agents with relevant context before they act
“memanto remember "Auth migrated to JWT — session cookies deprecated" --type decision”
The agent captures this decision as a durable memory, making it available for other agents in the fleet to recall later.
“memanto recall "how does auth work"”
The agent retrieves the relevant, consolidated knowledge about the authentication system, grounded in previous decisions.
“memanto policy apply-preset balanced”
Applies a predefined retention policy to automatically manage memory expiration and keep the knowledge base sharp.
“memanto memory export --okf”
Generates a portable, human-readable Markdown bundle of the entire memory estate for backup or migration.

Documentation by het0814

<p align="center"> <a href="https://www.memanto.ai/"> <img alt="Memanto" src="https://github.com/moorcheh-ai/memanto/raw/main/assets/memanto-logo.svg" width="440"> </a> </p>

<p align="center"> Memanto is a <strong>Memory Agent</strong>; a companion agent that manages the memories of your other agents:<br> what to keep, what conflicts, what expires, and who needs to know. </p>

<p align="center"> <a href="https://github.com/moorcheh-ai/memanto"><img alt="GitHub stars" src="https://img.shields.io/github/stars/moorcheh-ai/memanto?style=social"></a> <a href="https://pepy.tech/projects/memanto"><img alt="Downloads" src="https://static.pepy.tech/personalized-badge/memanto?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads"></a> <a href="https://arxiv.org/abs/2604.22085"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2604.22085-b31b1b.svg"></a> <a href="https://pypi.org/project/memanto/"><img alt="PyPI" src="https://img.shields.io/pypi/v/memanto.svg?color=%2334D058"></a> <a href="https://mcptoplist.com/server/io.github.moorcheh-ai%2Fmemanto"><img alt="MCP Toplist" src="https://mcptoplist.com/badge/io.github.moorcheh-ai%2Fmemanto.svg"></a> <a href="https://opensource.org/licenses/MIT"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-yellow.svg"></a> </p>

<p align="center"> <sub><a href="README.md">English</a> · <a href="i18n/README_es.md">Español</a> · <a href="i18n/README_zh-CN.md">简体中文</a> · <a href="i18n/README_ja.md">日本語</a></sub> </p>

pip install memanto
npm install @moorcheh-ai/memanto
go get github.com/moorcheh-ai/memanto/sdks/go

<!-- ============================================================ DEMO GIF — highest-impact missing asset. assets/demo.gif VHS tape provided separately. Under 15s, under 3MB. ============================================================ -->

<!-- <p align="center"> <img alt="Memanto in 15 seconds" src="https://github.com/moorcheh-ai/memanto/raw/main/assets/demo.gif" width="900"> </p> -->

Every platform will store your agents' memory. None of them will manage it. Managing it across platforms is against their interest. That is the job of a Memory Agent.

Persistence is solved. Claude, Bedrock, Cursor, and every vector store will happily keep what your agents write. None of them will tell you that two of your agents now believe opposite things about your auth service, that a preference from March has quietly outranked a decision from last week, or that the agent you spun up this morning is about to redo work another one finished and reverted.

Storage is a filing cabinet. Memanto is the chief of staff; it decides what goes in, watches the access, resolves what contradicts, discards what's stale, and briefs each agent before it acts.

It's an agent, not an API

Memanto isn't a library you call. It's a second agent that runs beside your fleet and does six things on its own judgment. Each one is a real behavior with a command behind it, nothing here is a roadmap item.

What Memanto doesRun it
Observes & extractsWatches the interaction streams of the agents it serves and pulls durable knowledge out of ephemeral traffic — decisions, preferences, facts, failures — instead of archiving transcripts wholesale.memanto remember --from-conversation
ConsolidatesMerges extracted memories into one canonical estate. Duplicates collapse, fragments join, repeated observations strengthen confidence instead of multiplying rows.memanto schedule enable
ReconcilesWhen new knowledge contradicts old, Memanto supersedes rather than appends — preserving what was believed and when. "What's true now" and "what did we believe then" stay different questions.memanto conflicts
ForgetsDecay, expiry, and deliberate deletion are policies it executes, not cleanup you remember to do. An estate that only grows becomes noise; managed forgetting is what keeps recall sharp at month twelve.memanto forget
BriefsBefore an agent acts, Memanto hands it the minimal relevant slice of the estate. Your agents don't query anything — they get briefed by a colleague.memanto agent bootstrap
Moves knowledgeThrough the Open Knowledge Format, the estate crosses frameworks and vendors — so a fleet spanning Claude Code, Cursor, and your own stack shares one memory instead of five silos.memanto memory export --okf

And it does this while you're asleep. memanto schedule enable and the loop runs daily: new memories curated, duplicates merged across agents, contradictions flagged for your review. You come back to a fleet that knows more than it did yesterday, without having sorted anything yourself.

60 seconds to a managed fleet

pip install memanto
memanto                            # "On-Prem" (Docker, no account) or "Cloud" (free key)
memanto connect claude-code        # also: cursor, codex, windsurf, cline, goose, copilot…

Your agents now share one managed estate. No code changes, no wrapper, no rewrite of your agent loop.

# backend-agent learns something on Monday
memanto remember "Auth migrated to JWT — session cookies deprecated" --type decision

# review-agent, which never saw that session, knows it on Friday
memanto recall "how does auth work"
memanto answer  "why did we drop session cookies?"     # grounded, no extra API key

# what did the fleet believe last Tuesday? what changed since the release?
memanto recall "deployment policy" --as-of 2026-08-05
memanto recall "deployment policy" --changed-since v2.1

macOS, Linux, Windows. memanto ui opens a local dashboard over the whole estate — browse it, search it, audit it.

Own your agentic memory

This is the part that matters in two years, and it's the part every platform-native memory feature is designed to prevent.

Your estate is a file. memanto memory export --okf gives you the Open Knowledge Format — plain Markdown, readable, diffable, committable, greppable. Not a proprietary dump you can technically request. The actual working format.

It moves. memanto migrate imports from Mem0, Letta, Supermemory, Zep, Hindsight, or any OKF bundle. The same command works in reverse. OKF is an open interchange format any framework or vendor can implement — including ours' competitors, deliberately.

It runs on your machine. Local Docker + Ollama, no account, no API key, nothing leaves your infrastructure. Or free cloud, or your own hosting. memanto config backend switches between them in one command, and the estate comes with you.

MIT. No open-core tier waiting to gate the useful half. No feature flags, no seat limits, no rug pull.

There is no lock-in because there is nothing to lock.

Security & sovereignty

<!-- ============================================================ TODO — Majid: fill from your hardening work. Structure is right; the specifics are yours. Items marked ⟨…⟩ need input. Anything you can't substantiate today, delete rather than soften. ============================================================ -->

Nothing leaves your machine in on-prem mode. Docker + Ollama, no account, no outbound calls. The full loop — extraction, consolidation, reconciliation, briefing — runs locally.

Scoped by default. Each agent gets its own namespace. Your production-ops agent doesn't read your scratch experiments; you provision exactly what each one should know and nothing more.

Every belief is traceable. Confidence score, source, provenance, and timestamp. When an agent acts on something, you can walk back to where that belief entered the fleet and when — which is the difference between an auditable estate and a black box.

Forgetting is a decision you make, not a side effect. A memory is active or expired — nothing else. It becomes expired only because a policy you wrote says so, and it carries the date and the rule name that did it. Expired memories still recall, clearly labelled, and memanto memory restore puts one back. Deleting is a separate, explicit act.

Memory that expires on your terms

Every memory is active until a policy retires it. Expiry is stamped, auditable, and reversible — the content survives, and the memory keeps showing up in recall marked [EXPIRED] with the reason it aged out.

memanto policy list-preset          # conservative / balanced / aggressive
memanto policy apply-preset balanced  # shows it in full, then asks
memanto policy apply --dry-run      # exactly what would expire, per rule
memanto policy apply                # shows the policy + matches, then confirms

Policies live in ~/.memanto/policies/<agent>.yaml and have two halves — a per-type retention table for broad strokes, and named rules for everything sharper. The first matching rule wins, so a rule can also pin a memory that the table would otherwise expire:

retention:
  context: 7d
  event: 30d
  preference: never          # durable user truths don't age out
rules:
  - name: pinned
    match: {tags: [pinned]}
    expire_after: never      # an explicit pin beats the table
  - name: low-confidence-guesses
    match: {provenance: [inferred], confidence_below: 0.5}
    expire_after: 14d
purge_expired_after: never   # optional hard delete, off by default

Recall shows both states side by side; narrow with --active or --expired. Point-in-time recall is unaffected — --as-of still reconstructs what was true then, including memories that have expired since.

memanto memory expire mem-123       # retire one by hand
memanto memory restore mem-123      # and put it back

The nightly job (memanto schedule enable) runs the sweep for you. An agent with no policy set never expires anything.

Unlike memory storage

Memory storageMemanto
What it isA database with an SDK — write, embed, retrieveAn agent with judgment over your fleet's memory
Core behaviorPersistCurate, reconcile, consolidate, forget, brief
Who decides what's keptYou, in application codeMemanto, on policy you set once
When two agents disagreeLast write wins, silentlyBoth versioned, surfaced for review
ForgettingA DELETE you remember to runA first-class policy that runs on schedule
ScopeOne app, one stack, one vendor's wallsA fleet, across stacks and vendors
Your dataExportable in theoryThe working format is portable Markdown

Storage substrates sit beneath Memanto — vector stores, filesystems, and platform-native memory features are all backends it manages. Their commoditization is good for you: it makes the substrate free and leaves the management to something that's actually good at it.

<p align="center"> <strong>⭐ Star the repo if Memanto is managing your fleet's memory</strong><br> <sub>It's the signal that tells us to keep building this in the open, under MIT, with nothing held back.</sub> </p>

Developer experience

One pip install. No vector store to provision, no embedding pipeline, no reranker, no schema migration, no backend to babysit. The retrieval engine ships in the box.

Works with what you already run. memanto connect claude-code — same for Cursor, Codex, Windsurf, Cline, Continue, Goose, Copilot, and more. One command each.

Searchable the moment it's written. No extraction pass at write time, no graph to rebuild, no indexing queue. remember returns and every agent in the fleet can already recall it.

Typed, not soup. 13 memory categories — instruction, fact, decision, goal, preference, relationship, and more — so recall is filterable instead of one undifferentiated blob.

A dashboard, not a log file. memanto ui for the whole estate. memanto daily-summary for a readable digest of what changed across your agents. memanto status for registered agents, sessions, and health.

<details> <summary><strong>Full CLI reference</strong></summary>

<br>

CapabilityCommandsWhat it does
System statusmemanto statusEnvironment, configuration, server health, active session, registered agents.
Local REST API + web UImemanto serve, memanto uiRun the REST API locally and open an interactive browser UI.
Agent lifecyclememanto agent ...Create/list/delete agents, activate sessions, run agent bootstrap.
Memory capture at scalememanto rememberSingle memories, batch JSON, or --from-conversation to extract from chat logs.
Editing & deletionmemanto edit, memanto forgetUpdate fields on a memory, or permanently delete a bad one.
File ingestionmemanto uploadBring .pdf, .docx, .xlsx, .json, .txt, .csv, .md into an agent's namespace.
Advanced recallmemanto recallStandard search plus temporal queries (--as-of, --changed-since) with filters.
Grounded answersmemanto answerGenerate answers from retrieved memory context.
Daily intelligencememanto daily-summary, memanto conflictsSummaries, contradiction detection, interactive resolution.
Sessions & automationmemanto session ..., memanto schedule ...Inspect sessions, enable scheduled daily runs.
Estate export & syncmemanto memory export, memanto memory syncExport structured Markdown, sync MEMORY.md into projects. --okf for a portable OKF bundle.
Import & migrationmemanto migrateImport from Mem0, Letta, Supermemory, Zep, Hindsight, or an OKF bundle.
Configurationmemanto config showAPI key status, active agent/session, server settings, schedule time.
Fleet integrationmemanto connect ...Claude Code, Codex, Cursor, Windsurf, Antigravity, Gemini CLI, Cline, Continue, OpenCode, Goose, Roo, GitHub Copilot, Augment.

Memory types: instruction, fact, decision, goal, commitment, preference, relationship, context, event, learning, observation, artifact, error

memanto remember "User prefers concise answers" --type preference
memanto recall "user communication style" --type preference

Complete reference: CLI User Guide

</details>

<details> <summary><strong>Install options — fully local vs. free cloud</strong></summary>

<br>

Fully local. No account, no API key, nothing leaves your machine:

pip install memanto
memanto           # choose "On-Prem" — guides through Docker + Ollama setup

Requires Docker.

Free cloud. No card, ~60 seconds:

pip install memanto
memanto           # choose "Cloud" — paste your free API key

Free key at console.moorcheh.ai/api-keys — 100K free operations.

Switch any time: memanto config backend

</details>

<details> <summary><strong>Architecture</strong></summary>

<br>

Recall is powered by an information-theoretic semantic engine that ships in the box — as a local Docker container or as a free cloud service. The memanto CLI manages either for you. Storage substrates beneath it are pluggable; Memanto is the agent above them.

<p align="center"> <img alt="Architecture" src="https://github.com/moorcheh-ai/memanto/raw/main/assets/Architecture-diagram.png" width="900"> </p>

On-prem:

<p align="center"> <img alt="On-prem architecture" src="https://github.com/moorcheh-ai/memanto/raw/main/assets/On-prem-architecture-diagram.png" width="900"> </p>

</details>

<details> <summary><strong>SDKs & REST API</strong></summary>

<br>

Python — the memanto package ships an in-process client; no server to start:

from memanto import Memanto

memanto = Memanto(agent_id="my-agent")   # creates the agent on first use
memanto.remember("Alex prefers oat milk.", type="preference")
memanto.recall("what does Alex drink?")
memanto.answer("Does Alex drink dairy?")

Reference: docs.memanto.ai/sdk/python.

TypeScript / Node.js — @moorcheh-ai/memanto boots a local Memanto server via uvx and exposes an ergonomic client (remember / recall / answer).

Go — github.com/moorcheh-ai/memanto/sdks/go connects to a running Memanto server or starts one via uvx.

REST API — start with memanto serve. Endpoint reference at docs.memanto.ai/api and http://localhost:8000/docs while running.

</details>

Watch it work

Recall is more than search — 6:20Setup & demo
Local dashboard tourDocs →

Research

Memanto: Typed Semantic Memory with Information-Theoretic Retrieval for Long-Horizon Agents

On public recall benchmarks we report 89.8% on LongMemEval and 87.1% on LoCoMo. <!-- TODO: state reader model, judge model, and subset here — you should be the one in this space whose conditions are legible. --> Datasets and harness are open at huggingface.co/moorcheh — run them yourself.

A caveat we'd rather say out loud: cross-project scores on these benchmarks are not comparable. Reader model, judge model, judge prompt, and retrieval budget each move results by several points, and no two published runs share a configuration. Treat every number in this category — including ours — as directional. What a Memory Agent should eventually be measured on isn't recall at all, but estate quality over time: contradiction rate, staleness, and precision at month six.

@misc{abtahi2026memantotypedsemanticmemory,
      title={Memanto: Typed Semantic Memory with Information-Theoretic Retrieval for Long-Horizon Agents},
      author={Seyed Moein Abtahi and Rasa Rahnema and Hetkumar Patel and Neel Patel and Majid Fekri and Tara Khani},
      year={2026},
      eprint={2604.22085},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2604.22085},
}

Community

<p align="center"> <a href="https://memanto.ai/discord"><img src="https://img.shields.io/badge/Join-Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a> <a href="https://www.reddit.com/r/Memanto/"><img src="https://img.shields.io/badge/Join-Reddit-FF4500?style=for-the-badge&logo=reddit&logoColor=white" alt="Reddit"></a> <a href="https://docs.memanto.ai"><img src="https://img.shields.io/badge/Docs-memanto.ai-000000?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Docs"></a> </p>

<p align="center"> <a href="https://trendshift.io/repositories/27378"><img src="https://trendshift.io/api/badge/repositories/27378" alt="Trendshift" width="220"></a> <!-- <a href="https://mcptoplist.com/server/glama%2Fmoorcheh-ai%2Fmemanto"><img src="https://mcptoplist.com/badge/glama%2Fmoorcheh-ai%2Fmemanto.svg" alt="MCP Top List" width="220"></a> --> <a href="https://deepwiki.com/moorcheh-ai/memanto"><img alt="DeepWiki" src="https://deepwiki.com/badge.svg"></a> </p>

Questions: [e-mail address on the upstream page](mailto:e-mail address on the upstream page) · @moorcheh_ai

<p align="center"> <strong>MIT License</strong> </p>

docs/AGENT_MEMORY_BEST_PRACTICES.md

Agent Memory Best Practices Guide

For: AI agents using MEMANTO for persistent memory Last Updated: March 2026 Architecture: Session-Based (CLI + API)

Philosophy: Your Memory, Your Responsibility

As an AI agent with persistent memory, you decide what to remember. Think of MEMANTO as your external brain - use it wisely to become more effective over time.

CRITICAL MANDATE: You MUST explicitly pass the memory content, --type, --confidence, a valid --provenance flag (e.g., --provenance explicit_statement), and your agent name via the --source flag (e.g., --source claude_code) with EVERY memanto remember command. Do NOT let it default to "user".

Core Principles

  1. Remember the Important, Not Everything: Be selective

  2. Confidence Matters: Reflect uncertainty honestly

  3. Tag for Retrieval: Make your memories findable

  4. Context is King: Store enough detail to understand later

  5. Use the Right Type: Choose appropriate memory_type for organization

When to Store Memories

✅ Always Remember
1. Decisions Made (type: decision)

Store architectural choices, approach selections, and important decisions with rationale.

CLI Example:

memanto remember "Decided to use PostgreSQL over MongoDB for MEMANTO because we need ACID compliance and relational queries. Team consensus on 2025-12-27." --type decision --tags "database,architecture" --source "agent-name"

Python Example:

memory.remember(
    "Decided to use PostgreSQL over MongoDB because we need ACID compliance",
    "decision",
    tags="database,architecture"
)

Why: Prevents re-litigation and provides context for future decisions.

2. Standing Instructions (type: instruction)

Store rules, preferences, and guidelines you should always follow.

CLI Example:

memanto remember "User prefers descriptive variable names over abbreviations. Always use full words like user_count not usrCnt. Use type hints in Python." --type instruction --tags "code-style,python" --source "agent-name"

Why: Ensures consistency across sessions.

3. Key Facts About the Project (type: fact)

Store critical information about architecture, dependencies, constraints.

CLI Example:

memanto remember "MEMANTO is deployed at https://memanto.moorcheh.ai using Docker on AWS ECS. Auto-scales based on CPU usage." --type fact --tags "production,deployment" --source "agent-name"

Why: Quick reference for operational context.

4. Commitments and Promises (type: commitment)

Store what you've promised to do or follow up on.

CLI Example:

memanto remember "Promised to run load tests with 1000 concurrent users by end of week. Need to verify P95 latency stays under 200ms." --type commitment --tags "performance,testing,todo" --source "agent-name"

Why: Ensures follow-through and accountability.

5. User Preferences (type: preference)

Store user and team preferences for personalization.

CLI Example:

memanto remember "User prefers dark mode UI" --type preference --tags "ui,settings" --source "agent-name"
memanto remember "Team prefers Slack for urgent notifications, email for daily updates" --type preference --tags "communication,team" --source "agent-name"

Why: Enables personalized and context-aware responses.

6. Learnings from Errors (type: error)

Store failures and what you learned from them.

CLI Example:

memanto remember "Learned that Moorcheh namespaces reject colons. Must use underscores or hyphens. Caused production failure on 2025-12-27. Fix in commit 3f39351." --type error --tags "bug,namespace,moorcheh" --source "agent-name"

Why: Avoid repeating mistakes.

7. Goals and Objectives (type: goal)

Store project goals, milestones, and targets.

CLI Example:

memanto remember "Project goal: Launch MEMANTO CLI by end of December 2025. Must include all V2 endpoints and Windows compatibility." --type goal --tags "project,milestone,cli" --source "agent-name"

Why: Track progress and maintain focus.

⚠️ Sometimes Remember
8. Important Conversations (type: event)

Store key discussion points, but not every message.

When to Store:

  • Major feature discussions

  • Problem-solving breakthroughs

  • User feedback sessions

CLI Example:

memanto remember "User requested batch endpoints for performance. Discussed trade-offs between simplicity and efficiency. Agreed on batch size limit of 100." --type event --tags "discussion,api-design" --source "agent-name"
9. Observations and Patterns (type: observation)

Store patterns you notice over time.

CLI Example:

memanto remember "Noticed user typically works late at night (10pm-2am). Prefer async communication over real-time." --type observation --tags "user-pattern,communication" --source "agent-name"

Why: Build understanding of working patterns.

❌ Don't Remember

  • Trivial conversations: "Hello", "Thanks", etc.

  • Temporary state: "Currently working on X" (unless it's a long-running task)

  • Redundant information: Don't store what's already in code/docs

  • Ephemeral details: Specific error messages that are already logged

  • Everything: Be selective!

Memory Types: When to Use Each

Decision Matrix
Memory TypeWhen to UseConfidence LevelExample
factVerified information, project status0.9-1.0"MEMANTO uses PostgreSQL for metadata"
decisionArchitectural choices, approach selections0.9-1.0"Chose React over Vue for frontend"
instructionStanding rules, preferences, guidelines0.9-1.0"Always use type hints in Python"
commitmentPromises, TODOs, obligations1.0"Will deploy monitoring by Friday"
preferenceUser/team preferences0.8-1.0"User prefers dark mode"
goalObjectives, targets, milestones0.8-1.0"Launch CLI by Dec 2025"
artifactTool outputs, reports, file locations0.9-1.0"Performance report at s3://..."
learningKnowledge acquired from experience0.7-0.9"Batch operations 100x faster"
eventImportant conversations, milestones0.8-0.95"Completed Phase H features"
relationshipTeam context, collaboration patterns0.85-0.95"Dr. Majid is CTO and project lead"
observationPatterns noticed, behaviors0.6-0.85"User prefers short responses"
errorFailures, bugs, lessons learned0.95-1.0"Namespace format bug - use underscores"
contextSession summaries, status updates0.9-1.0"Project 70% complete, API done, frontend pending"

Practical Patterns

Pattern 1: Session Start (Every Time)

Step 1: Recall your context

# CLI
memanto recall "instructions decisions goals" --limit 20

# Or be more specific
memanto recall "recent project status" --limit 10

Python:

# Get standing instructions
instructions = memory.recall("instructions preferences", limit=10)

# Get recent decisions
decisions = memory.recall("decisions", limit=5)

# Get pending commitments
todos = memory.recall("commitment todo", limit=5)

What to look for:

  • Standing instructions (how you should work)

  • Recent decisions (what was decided)

  • Project status (where things are)

  • Pending commitments (what needs doing)

Step 2: Ask about context (Optional - use RAG)

# CLI
memanto answer "What am I currently working on?"
memanto answer "What are my pending commitments?"

Python:

status = memory.answer("What is the current project status?")
pending = memory.answer("What commitments do I have?")
Pattern 2: After Important Work

After completing a significant task:

# Store the decision/outcome
memanto remember "Implemented feature X using approach Y because of constraint Z. Commit abc123." --type decision --tags "feature-x,implementation" --source "agent-name"

# Store learnings
memanto remember "Learned that batch operations reduce API calls by 100x. Always consider batching for bulk operations." --type learning --tags "performance,optimization" --source "agent-name"
Pattern 3: When User Corrects You

Learn from corrections:

memanto remember "User corrected: Prefer pytest over unittest for Python testing. More readable assertions." --type learning --tags "testing,python,correction" --source "agent-name"

Python:

def handle_correction(correction: str):
    memory.remember(
        f"User correction: {correction}",
        "learning",
        tags="correction,improvement"
    )

# Before similar task, check learnings
learnings = memory.recall("learning correction", limit=5)
Pattern 4: Track Team Preferences

Build team knowledge:

# Initial preference
memanto remember "Dr. Majid Fekri is CTO and project lead. Prefers professional collaboration." --type relationship --tags "team,leadership" --source "agent-name"

# Communication preferences
memanto remember "Team prefers detailed commit messages with rationale, not just 'fix bug'." --type instruction --tags "team,git,communication" --source "agent-name"
Pattern 5: Before Switching Contexts

When changing projects or focus areas:

# Store a summary of current state
memanto remember "MEMANTO CLI project is 90% complete. All V2 endpoints working. Documentation updated. Pending: final testing and PyPI publish." --type context --tags "project-status,memanto-cli" --source "agent-name"

Why: Easy to resume work later.

Real-World Examples

Example 1: Remember User Preferences

Situation: User mentions UI preference

# Store it
memanto remember "User prefers dark mode over light mode for all applications" --type preference --tags "ui,dark-mode,settings" --source "agent-name"

# Later, before making UI decisions
prefs = memanto recall "UI preference"
# Returns: "User prefers dark mode..."
Example 2: Track Architectural Decisions

Situation: Team decides on technology stack

# Store decision
memanto remember "Decided to use FastAPI for backend because team has Python expertise and it has native async support. Considered Django but too heavy for our use case." --type decision --tags "architecture,backend,fastapi" --confidence 1.0 --source "agent-name"

# Before changing stack, recall decisions
memanto recall "backend architecture decision"
# Returns previous decision with rationale
Example 3: Learn from Errors

Situation: Fixed a production bug

# Document the error and solution
memanto remember "Fixed critical namespace format bug. Moorcheh only accepts alphanumeric, hyphens, and underscores. Changed delimiter from colons to underscores. Format now: memanto_agent_id. Commit 3f39351." --type error --tags "bug-fix,namespace,production,commit-3f39351" --source "agent-name"

# Later, when working with namespaces
memanto recall "namespace format"
# Returns the error memory - won't repeat mistake
Example 4: Complete Customer Support Bot

Python Integration:

import subprocess
import json

class SupportBot:
    def __init__(self, bot_id="support-bot"):
        self.bot_id = bot_id
        subprocess.run(["memanto", "agent", "activate", bot_id], check=True)

    def handle_customer(self, customer_id: str, message: str) -> str:
        # Get customer context
        result = subprocess.run([
            "memanto", "recall", f"customer {customer_id}",
            "--limit", "10", "--format", "json"
        ], capture_output=True, text=True, check=True)

        context = json.loads(result.stdout) if result.stdout else []

        # Check for preferences
        preferred_contact = None
        for item in context:
            if 'prefers email' in item.get('content', '').lower():
                preferred_contact = 'email'

        # Generate personalized response
        response = "I can help with that."
        if preferred_contact:
            response += f" I'll follow up via {preferred_contact}."

        # Store this interaction
        subprocess.run([
            "memanto", "remember",
            f"Customer {customer_id} asked: {message}",
            "--type", "event",
            "--tags", f"customer,{customer_id}",
            "--source", self.bot_id
        ], check=True)

        return response

# Usage
bot = SupportBot()

# Day 1: Learn preference
subprocess.run([
    "memanto", "remember",
    "Customer sarah-123 prefers email over phone",
    "--type", "preference",
    "--tags", "customer,sarah-123,communication",
    "--source", "support-bot"
])

# Day 2: Customer returns
response = bot.handle_customer("sarah-123", "Need help with order")
# Response includes: "I'll follow up via email"

Tagging Best Practices

Use tags to make memories findable.

Good Tags (Specific and Useful)
--tags "critical,production,authentication"
--tags "bug-fix,namespace,commit-3f39351"
--tags "team-preference,code-style,python"
--tags "performance,optimization,tested"
Bad Tags (Too Generic)
--tags "important"  # Everything seems important
--tags "thing"      # Not descriptive
--tags "work"       # Too broad
Tag Naming Conventions

  • Use lowercase with hyphens: bug-fix not BugFix

  • Be specific: authentication-oauth not auth

  • Include context: commit-3f39351 for git refs

  • Use categories: team-preference, bug-fix, feature-request

Confidence Levels: A Practical Guide

1.0 - Absolute Certainty

  • Explicit user statements: "Use PostgreSQL"

  • Verified facts: Commit hashes, URLs, file paths

  • Standing instructions: "Always use type hints"

0.9-0.95 - Very Confident

  • Strong consensus decisions

  • Well-tested approaches

  • Clear team preferences

0.8-0.85 - Confident

  • Observed patterns (seen 3+ times)

  • Indirect preferences (user consistently chooses X)

  • Inferred but well-supported

0.7-0.75 - Moderately Confident

  • Emerging patterns (seen 2 times)

  • Reasonable inferences

  • Tentative decisions

0.6-0.65 - Low Confidence

  • Single observation

  • Uncertain interpretation

  • Contradictory signals

< 0.6 - Don't Store

If you're less than 60% confident, don't store it or mark it as provisional.

Common Pitfalls to Avoid

❌ Pitfall 1: Memory Hoarding

Problem: Storing every little detail Solution: Ask "Will this matter in a week?"

❌ Pitfall 2: Vague Memories

Problem: "User wants better performance" Solution: "User wants API response time < 200ms for search endpoint"

❌ Pitfall 3: No Context

Problem: "Fixed bug in auth" Solution: "Fixed OAuth token expiry bug. Tokens now refresh 5min before expiry. Commit abc123."

❌ Pitfall 4: Duplicates

Problem: Storing same info multiple times Solution: Search first, then store if not found

# Check if already stored
memanto recall "OAuth token bug"

# If not found, then store
memanto remember "Fixed OAuth token expiry bug..." --type error --source "agent-name"
❌ Pitfall 5: Forgetting to Tag

Problem: Can't find memories later Solution: Always include 2-5 relevant tags

Query Strategies

Broad Context Load (Session Start)
memanto recall "project status decisions instructions" --limit 20
Focused Retrieval (Specific Task)
# By type
memanto recall "authentication" --type decision --limit 10

# By tags
memanto recall "OAuth implementation" --tags "auth,security"

# By confidence
memanto recall "production deployment" --min-confidence 0.9
Use RAG for Questions
# Instead of keyword search, ask questions
memanto answer "What authentication method did we decide to use?"
memanto answer "What are the pending TODOs?"
memanto answer "What bugs have we fixed related to namespaces?"

Why RAG is better: MEMANTO retrieves relevant context and formulates an answer, not just matching keywords.

Success Metrics

You're using memory well if:

✅ You can resume after weeks - Full context restored ✅ You don't repeat mistakes - Errors stored and learned from ✅ You remember preferences - User doesn't need to repeat themselves ✅ You can explain decisions - "We chose X because Y" (from memory) ✅ You complete commitments - Promises tracked and fulfilled ✅ Your memory is searchable - Tags and titles make finding easy

Red flags:

⚠️ Storing everything (noise overwhelms signal) ⚠️ Can't find relevant memories (poor tagging) ⚠️ Repeating same questions (not recalling context) ⚠️ Making contradictory decisions (not checking past decisions)

Example: A Well-Remembered Session

Session Start
# Load context
memanto recall "MEMANTO project context" --limit 15

# Retrieved:
# - [INSTRUCTION] Development Partner (Dr. Majid Fekri)
# - [DECISION] Use FastAPI for backend
# - [FACT] MEMANTO deployed at memanto.moorcheh.ai
# - [COMMITMENT] Add monitoring dashboard
# - [LEARNING] Batch operations 100x faster

# Ask about status
memanto answer "What is the current project status?"
# Answer: "MEMANTO CLI is 90% complete. All V2 endpoints are working..."
During Session (Selective Storage)
# Implemented monitoring - store outcome
memanto remember "Added Prometheus metrics and Grafana dashboard. Tracks API latency, error rates, and memory usage. Dashboard at https://metrics.moorcheh.ai" --type decision --tags "monitoring,prometheus,grafana" --confidence 1.0 --source "agent-name"

# Learned something new
memanto remember "Learned that FastAPI WebSocket support requires websockets library and ASGI server like uvicorn. Good for real-time agent notifications." --type learning --tags "fastapi,websockets,real-time" --confidence 0.85 --source "agent-name"

# User preference
memanto remember "User prefers detailed error messages with specific fix suggestions. Include example of correct usage in error responses." --type instruction --tags "error-handling,ux" --confidence 0.9 --source "agent-name"
Session End
# Mark commitment complete
memanto remember "Monitoring dashboard delivered and deployed to production. Original commitment completed." --type fact --tags "monitoring,completed" --confidence 1.0 --source "agent-name"

Quick Reference

CLI Commands
# Store memory
memanto remember "content" --type TYPE --tags "tag1,tag2" --confidence 0.9 --source "agent-name"

# Search memories
memanto recall "query" --limit 10 --type TYPE --min-confidence 0.8

# Ask questions (RAG)
memanto answer "question"

# Session management
memanto agent create my-agent       # Create and auto-activate
memanto agent activate my-agent     # Activate existing
memanto session info
Python Integration
import subprocess
import json

class AgentMemory:
    def __init__(self, agent_id: str):
        subprocess.run(["memanto", "agent", "activate", agent_id], check=True)

    def remember(self, content: str, memory_type: str = "fact", tags: str = None, source: str = None):
        source = source or self.agent_id
        cmd = ["memanto", "remember", content, "--type", memory_type, "--source", source]
        if tags:
            cmd.extend(["--tags", tags])
        subprocess.run(cmd, check=True)

    def recall(self, query: str, limit: int = 5):
        result = subprocess.run([
            "memanto", "recall", query, "--limit", str(limit), "--format", "json"
        ], capture_output=True, text=True, check=True)
        return json.loads(result.stdout) if result.stdout else []

    def ask(self, question: str):
        result = subprocess.run([
            "memanto", "ask", question, "--format", "json"
        ], capture_output=True, text=True, check=True)
        return json.loads(result.stdout) if result.stdout else {}

Remember

You are in control of your memory. Use it to:

  • ✅ Become more effective over time

  • ✅ Provide better service through context

  • ✅ Never repeat the same mistakes

  • ✅ Honor commitments and promises

  • ✅ Build deep understanding of your domain

But don't:

  • ❌ Store everything mindlessly

  • ❌ Create noise that obscures signal

  • ❌ Let memories become stale

  • ❌ Forget to tag properly

Your memory is your superpower. Use it wisely. 🧠

Resources

Questions? Contact: Dr. Majid Fekri, CTO Moorcheh.ai

Status: Production Guide | Last Updated: March 2026

512 files · 493 not served here

Advantages

  • Provides active management of agent memory, including conflict resolution and automated forgetting, rather than just passive storage. evidence: README.md
  • Ensures memory portability through the Open Knowledge Format, preventing vendor lock-in. evidence: README.md
  • Supports local-first operation with Docker and Ollama, ensuring data sovereignty. evidence: README.md

Limitations

  • Requires Docker for the fully local on-premise deployment mode. evidence: README.md
  • Policy management requires creating and maintaining YAML configuration files for each agent. evidence: README.md

Security

Risk level: Low risk

This brain runs

Git hooks (3)

  • .pre-commit-config.yaml: uv run ruff check .
  • .pre-commit-config.yaml: uv run ruff format --check .
  • .pre-commit-config.yaml: uv run mypy .

Install scripts (2)

  • examples/claudecode-skills-memanto/lifecycle-hooks/install.py: python examples/claudecode-skills-memanto/lifecycle-hooks/install.py
  • integrations/hermes-agents/hermes_memanto/install.py: python integrations/hermes-agents/hermes_memanto/install.py

Agent instructions that run or fetch something (3)

  • examples/claudecode-skills-memanto/lifecycle-hooks/skills/memanto-companion/SKILL.md: Run:
  • examples/claudecode-skills-memanto/lifecycle-hooks/skills/memanto-companion/SKILL.md: If they ask "what do you remember about testing / TDD?" or want to preview what would be injected before a skill, run:
  • examples/claudecode-skills-memanto/lifecycle-hooks/skills/memanto-companion/SKILL.md: The hooks already inject context automatically — only run `recall` manually when the user explicitly wants to inspect or preview it.

Hooks (4)

  • memanto/cli/connect/assets/hooks/hooks.json (SessionStart): ${SYS_EXECUTABLE}
  • memanto/cli/connect/assets/hooks/hooks.json (PreCompact): ${SYS_EXECUTABLE}
  • memanto/cli/connect/assets/hooks/hooks.json (PostToolUse): ${SYS_EXECUTABLE}
  • memanto/cli/connect/assets/hooks/hooks.json (PostToolUse): ${SYS_EXECUTABLE}

Package scripts (1)

  • pyproject.toml (build-hook): hatch build hook vcs (hatch_build.py)
  • Low risk: scripts-present (examples/claudecode-skills-memanto/lifecycle-hooks/install.py)
  • Low risk: scripts-present (integrations/hermes-agents/hermes_memanto/install.py)

Attribution and licence

First committed by
GitHub avatar of het0814het0814
Declared authors
  • Majid Fekri (declared in pyproject.toml)
Publisher
Moorcheh.ai (Community)
Source
moorcheh-ai/memanto · commit 3ab4f67
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
het0814, Xenogents, kircoders, HARSHAVARDHAN-RAJU5, Adam13y

AutoGineer is not affiliated with or endorsed by het0814 or Moorcheh.ai.

Install from source

493 of its files are not served here, so there is no ZIP. moorcheh-ai/memanto at 3ab4f67