# https://github.com/moorcheh-ai/memanto Project Manual

Generated at: 2026-07-02 20:39:46 UTC

## Table of Contents

- [Overview & System Architecture](#page-1)
- [CLI Commands, TypeScript SDK & Agent Integrations](#page-2)
- [Memory Model, Backend Services & REST API (v2)](#page-3)
- [Deployment, Configuration & Operations](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### Related Pages

Related topics: [CLI Commands, TypeScript SDK & Agent Integrations](#page-2), [Memory Model, Backend Services & REST API (v2)](#page-3), [Deployment, Configuration & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)
- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)
- [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)
- [memanto/app/services/summary_visualization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py)
- [memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py)
- [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)
- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
- [integrations/mcp/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/mcp/README.md)
- [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)
- [integrations/hermes-agents/hermes_memanto/PLUGIN_README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/hermes-agents/hermes_memanto/PLUGIN_README.md)
- [examples/langgraph-memanto/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md)
</details>

# Overview & System Architecture

## Purpose & Scope

Memanto is a **typed semantic memory layer for long-horizon AI agents**. It provides durable, structured storage and information-theoretic retrieval for memories that agents accumulate across sessions, projects, and external tool calls. Rather than treating memory as an opaque vector store, Memanto enforces a fixed taxonomy of 13 memory types and 6 provenance labels at write time, so conflicts, supersedes, and confidence can be resolved algorithmically rather than left to the LLM's context window. Source: [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)

The system is built on top of the **Moorcheh API**, which provides the backend tenant, namespace, and vector storage primitives. Memanto adds the agent-facing abstractions: typed memory records, agent patterns, conflict resolution, export, daily analysis, and a stable surface area for multiple language SDKs. Source: [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)

The project ships in v0.2.4 with three concrete deliverables that shape the architecture:

- An official **TypeScript SDK** (`@moorcheh-ai/memanto`) with lifecycle hooks and OpenAPI-generated types.
- A new **`memanto edit`** command for in-place memory updates, plus v2 memory route response models.
- **Security hardening fixes** for cross-agent authorization, upload path-traversal, and secret leakage in the UI config endpoint.

These releases expand the client surface (CLI → Python SDK → TypeScript SDK → MCP → FastAPI) while tightening the server-side boundary.

## High-Level Architecture

Memanto is organized into a small number of well-bounded layers. The diagram below shows how an agent (or its harness) reaches typed memory through one of several client surfaces, validates through a shared type system, and ultimately persists through the Moorcheh backend.

```mermaid
flowchart TB
    subgraph Clients["Client Surfaces"]
        CLI["memanto CLI<br/>(memanto/cli)"]
        PYSDK["Python SDKClient<br/>(memanto/cli/client/sdk_client.py)"]
        TSSDK["TypeScript SDK<br/>(@moorcheh-ai/memanto)"]
        MCP["MCP Server<br/>(integrations/mcp)"]
        LEGACY["FastAPI /v1 routes<br/>(memanto/app/legacy/memory.py)"]
    end

    subgraph Domain["Domain & Services"]
        TYPES["Type System<br/>13 memory types, 6 provenance<br/>(memanto/app/constants.py)"]
        AGENTS["Agent Service<br/>create/list/get agents"]
        MEMRW["MemoryWriteService<br/>(conflict-resolution write path)"]
        MEMREAD["Recall / Answer<br/>(information-theoretic retrieval)"]
        EXPORT["MemoryExportService<br/>memory.md writer"]
        DAILY["DailyAnalysisService<br/>+ SummaryVisualizationService"]
    end

    subgraph Backend["Backend"]
        MOORCHEH["Moorcheh API<br/>tenant / namespace / vector store"]
    end

    CLI --> PYSDK
    TSSDK --> TYPES
    MCP --> TYPES
    LEGACY --> TYPES
    PYSDK --> AGENTS
    PYSDK --> MEMRW
    PYSDK --> MEMREAD
    PYSDK --> EXPORT
    PYSDK --> DAILY
    AGENTS --> MOORCHEH
    MEMRW --> MOORCHEH
    MEMREAD --> MOORCHEH
```

All client surfaces converge on the same domain layer and ultimately on Moorcheh. Source: [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py), [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)

## Core Data Model

The type system is the architectural keystone. `memanto/app/constants.py` defines four sealed enumerations that gate every write:

| Enumeration | Count | Values |
|---|---|---|
| `MemoryType` | 13 | `fact`, `preference`, `goal`, `decision`, `artifact`, `learning`, `event`, `instruction`, `relationship`, `context`, `observation`, `commitment`, `error` |
| `ProvenanceType` | 6 | `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported` |
| `StatusType` | 4 | `active`, `superseded`, `deleted`, `provisional` |
| `VALID_PATTERNS` | 3 | `support`, `project`, `tool` |

Updates are also constrained: `ALLOWED_UPDATE_FIELDS` whitelists exactly `title`, `content`, `type`, `confidence`, `tags`, `source`. Updates outside that whitelist are rejected, which makes the new `memanto edit` command safe to expose as a tool. Source: [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)

Agents are first-class objects. `create_agent` enforces a pattern from `{"support", "project", "tool"}` and persists an `agent_id` plus a derived `namespace` on the backend. Source: [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)

Memories are further partitioned by `scope_type` / `scope_id` for batch writes (up to 100 per request), `actor_id`, `source`, optional `ttl_seconds`, and a `user_confirmed` flag that participates in the conflict-resolution flow. Source: [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)

## Interface Surfaces

Memanto exposes the same domain through several entry points, each with a different privilege model.

- **`memanto` CLI**: The richest surface. It includes memory.md export (which walks all 13 types and writes a structured Markdown file via `MemoryExportService`), `memanto edit` for in-place updates, and `memanto migrate` with bundled runners for **Letta**, **mem0**, and **Supermemory** exports. Source: [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py), [memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py), [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)

- **Python `SdkClient`**: A programmatic API used by integrations and the CLI. It delegates writes to `MemoryWriteService`, which drives conflict resolution through a `context={"user_confirmed": ...}` flag rather than raw upserts. Source: [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py), [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)

- **TypeScript SDK (`@moorcheh-ai/memanto`)**: Published as `@moorcheh-ai/memanto`, targeting `node >= 20`, with lifecycle hooks and OpenAPI-generated types to keep Python and TypeScript clients in sync. Source: [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)

- **MCP server (`integrations/mcp`)**: Exposes `remember`, `recall`, `answer`, plus point-in-time and differential recall; agent-admin tools are gated behind `MEMANTO_EXPOSE_ADMIN=true`. Source: [integrations/mcp/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/mcp/README.md)

- **Agent-framework integrations**: CrewAI uses tool wrappers and explicitly disables CrewAI's built-in `memory=True` to avoid dual-memory drift; Hermes scopes writes per `{identity}` profile; LangGraph examples include `basic_integration`, `cross_session_recall`, `research_pipeline`, and a custom `MemantoBaseStore` CheckpointSaver. Source: [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md), [integrations/hermes-agents/hermes_memanto/PLUGIN_README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/hermes-agents/hermes_memanto/PLUGIN_README.md), [examples/langgraph-memanto/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md)

## Background Services

Two services run outside the request path and are worth calling out for the architecture overview:

- **`DailyAnalysisService`** reconstructs a day's session Markdown files for an agent, prompts the active LLM (`settings.SUMMARY_MODEL`) for an executive-summary report, and then delegates visual insights to `SummaryVisualizationService`. Source: [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)

- **`SummaryVisualizationService`** parses session headings (`### [YYYY-MM-DD HH:MM:SS] [TYPE] title`) and confidence lines to emit an ASCII timeline, type distribution, and confidence overview, appended under a `## 📊 Visual Insights` section. Source: [memanto/app/services/summary_visualization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py)

## Common Failure Modes

Because all writes pass through the same validator and conflict-resolution flow, the system fails in predictable ways:

- Invalid write: rejected at the type system if `type`, `provenance`, or `pattern` is outside the allowed set. Source: [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- Conflict: surfaced through the conflict-resolution flow (`memanto conflicts resolve`), not free-form delete. Source: [examples/langgraph-memanto/memanto_base_store/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/memanto_base_store/README.md)
- Cross-agent access: blocked by the v0.2.4 authorization hardening, which scopes each API key to its own agents.
- Migration compatibility: Letta, mem0, and Supermemory all run through a shared `migrate.runner` that loads an export, previews it, and only then commits. Source: [memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py)

## See Also

- [Memory Types & Provenance Reference](#)
- [CLI Command Reference](#)
- [MCP Server Configuration](#)
- [TypeScript SDK Guide](#)

---

<a id='page-2'></a>

## CLI Commands, TypeScript SDK & Agent Integrations

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Memory Model, Backend Services & REST API (v2)](#page-3), [Deployment, Configuration & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
- [memanto/cli/commands/_shared.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/_shared.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [memanto/cli/client/sdk_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py)
- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)
- [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)
- [memanto/app/services/summary_visualization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py)
- [memanto/app/models/__init__.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/models/__init__.py)
- [integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)
- [examples/langgraph-memanto/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md)
- [examples/langgraph-memanto/memanto_base_store/README.md](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/memanto_base_store/README.md)
- [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)
</details>

# CLI Commands, TypeScript SDK & Agent Integrations

## Overview

Memanto exposes three complementary surfaces for interacting with its typed semantic memory layer: a **Python CLI** for terminal-first workflows, an **official TypeScript SDK** (`@moorcheh-ai/memanto`) for Node.js environments, and **framework-specific integrations** for popular agent runtimes (CrewAI, LangGraph, and IDE clients such as Cursor). Together they provide ergonomic entry points while sharing the same 13-type memory model defined in [`memanto/app/constants.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py): `instruction`, `fact`, `decision`, `goal`, `commitment`, `preference`, `relationship`, `context`, `event`, `learning`, `observation`, `artifact`, `error`.

The v0.2.4 release specifically hardened this surface area by shipping the TypeScript SDK, a new `memanto edit` command for in-place memory updates, v2 memory route response models, and several security fixes (cross-agent authorization, upload path-traversal, and secret leakage in the UI config endpoint).

## CLI Command Architecture

### Command Groups

The CLI is built on Typer and registered in [`memanto/cli/commands/_shared.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/_shared.py). A single root `app` exposes seven subcommands:

| Subcommand | Purpose |
|---|---|
| `agent` | Agent management (create/list/get agents with `support` / `project` / `tool` patterns) |
| `session` | Legacy aliases for agent activation |
| `config` | Configuration commands |
| `schedule` | Daily summary scheduling |
| `memory` | Memory management (remember/recall/edit/export) |
| `connect` | Connect Memanto to external IDEs (Cursor, Claude Code, etc.) |
| `migrate` | Import memories from Mem0, Letta, or Supermemory |

A `Rich` console renders errors via a consistent red `Panel` through the `_error()` helper, keeping UX predictable across commands.

### CLI Client (`SdkClient`)

The CLI delegates work to `SdkClient` (defined in [`memanto/cli/client/sdk_client.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/sdk_client.py) and [`memanto/cli/client/direct_client.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)), which wraps the REST API. Key capabilities include:

- `create_agent(agent_id, pattern, description)` — validates `pattern` against `_VALID_PATTERNS` (`support`, `project`, `tool`), constructs an `AgentCreate` model, and returns the registered agent info with `agent_id`, `namespace`, and `created_at`.
- `list_agents()` / `get_agent(agent_id)` — discovery operations.
- `recall_memory_md()` — exports all memories grouped by the 13 canonical types into a Markdown file, defaulting to `~/.memanto/exports/{agent_id}_memory.md`. It iterates `MEMORY_TYPE_ORDER` from [`memory_export_service.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py), runs `recall(query="*", limit=25, type=[mem_type])` per type, then writes a structured Markdown report.

### Memory Workflow Services

Beyond raw CRUD, the CLI surfaces higher-level summarization flows:

- [`memanto/app/services/daily_analysis_service.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py) globs session summary files matching `{agent_id}_{date}_*_summary.md`, concatenates them, and asks a Moorcheh `answer.generate` call to produce an Executive Summary plus Key Themes report.
- [`memanto/app/services/summary_visualization_service.py`](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/summary_visualization_service.py) appends ASCII-art activity timelines, type-distribution charts, and confidence overviews parsed via two regexes (`_HEADING_RE` for `### [timestamp] [TYPE] title` and `_CONFIDENCE_RE` for `**Confidence**: \`0.85\``).

```mermaid
flowchart LR
    A[CLI: memanto remember/recall/edit] --> B[SdkClient]
    B --> C[Memanto REST API]
    C --> D[(Moorcheh Vector Store)]
    C --> E[Session Summaries]
    E --> F[DailyAnalysisService]
    F --> G[VisualizationService]
    G --> H[Markdown Summary File]
    B --> I[MemoryExportService]
    I --> J[memory.md per agent]
```

## TypeScript SDK (`@moorcheh-ai/memanto`)

The official Node.js client is published as `@moorcheh-ai/memanto` per [`sdks/typescript/package.json`](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json). Notable characteristics:

- **Dual build output** via `tsup` produces both ESM (`./dist/index.js`) and CJS (`./dist/index.cjs`) with type declarations (`./dist/index.d.ts`).
- **OpenAPI-first** — `scripts/fetch-openapi.mjs` fetches the live Memanto OpenAPI spec, and `@hey-api/openapi-ts` regenerates types so the SDK stays in lockstep with the v2 response models added in v0.2.4. Regenerate with `npm run openapi:regenerate`.
- **Toolchain**: TypeScript `^5.4.0`, `vitest` `^4.1.9` for tests, Node `>=20` engine requirement.
- **Exports a `Memanto` client** with `remember` / `recall` / `answer` methods, and per the release notes includes lifecycle hooks so callers can react to session creation, activation, and teardown.

The keywords array (`memanto`, `memory`, `ai`, `agents`, `moorcheh`, `rag`) reflects its positioning as a thin, typed wrapper over the same REST API the CLI uses.

## Agent Framework Integrations

### CrewAI

[`integrations/crewai/README.md`](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md) documents a **tool-based** integration pattern rather than implementing CrewAI's native `StorageBackend` interface. Rationale given in the README:

- **Information-theoretic search operates on text**, so it doesn't accept raw vector embeddings like native backends (Hindsight, Mengram) do.
- **Rich metadata** — the LLM tool-caller can choose any of the 13 memory types, set confidence scores, and tag at write time.
- **No dual-memory risk** — all Crews explicitly set `memory=False` to prevent CrewAI from injecting its own LanceDB-backed "Search memory" / "Save to memory" tools alongside the Memanto tools.

All agents in the example share a single `agent_id` (`crewai-research-team`) that maps to one Memanto namespace (`memanto_agent_{agent_id}`), giving isolation between different crews.

### LangGraph

[`examples/langgraph-memanto/README.md`](https://github.com/moorcheh-ai/memanto/blob/main/examples/langgraph-memanto/README.md) ships four example directories:

| Example | Purpose |
|---|---|
| `basic_integration/` | Drop-in tools inside a simple LangGraph agent |
| `cross_session_recall/` | Remembers facts/preferences across separate threads |
| `research_pipeline/` | Multi-agent research → synthesize flow |
| `custom_memory_saver/` | Direct integration at the LangGraph `CheckpointSaver` level |

The `memanto_base_store` example implements `MemantoStore(BaseStore)` so swapping in `from langgraph.store.memory import InMemoryStore` to `MemantoStore(client, agent_id=...)` is a one-line change to `builder.compile(checkpointer=..., store=...)`.

### IDE Connectors

Per the project `README.md`, `memanto connect <tool>` installs rules into Cursor, Claude Code, Codex CLI, Windsurf, Aider, OpenCode, Goose, Roo, GitHub Copilot, and Augment — either project-scoped or global (`--global`). For Cursor specifically, this creates `.cursor/rules/memanto.mdc` (memory instructions) and `.cursor/skills/memanto/SKILL.md` (memory type guide).

## See Also

- [Memanto REST API](https://docs.memanto.ai/api) — endpoint reference (`http://localhost:8000/docs` when `memanto serve` is running)
- [CLI User Guide](https://docs.memanto.ai/cli) — complete command reference
- [Research paper: Memanto — Typed Semantic Memory with Information-Theoretic Retrieval](https://huggingface.co/papers/2604.22085)
- Project README: [README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)

---

<a id='page-3'></a>

## Memory Model, Backend Services & REST API (v2)

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [CLI Commands, TypeScript SDK & Agent Integrations](#page-2), [Deployment, Configuration & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [memanto/app/models/__init__.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/models/__init__.py)
- [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)
- [memanto/app/routes/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/routes/memory.py)
- [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py)
- [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)
- [memanto/app/services/conversation_memory_extraction_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/conversation_memory_extraction_service.py)
- [memanto/app/legacy/context_summarization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/context_summarization_service.py)
- [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py)
- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
</details>

# Memory Model, Backend Services & REST API (v2)

## Overview

Memanto's backend is a typed, scope-aware memory layer that turns long-horizon agent activity into retrievable, semantically tagged memories. The v2 API surface — exposed through [memanto/app/routes/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/routes/memory.py) and the legacy router in [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py) — provides typed write, batch write, recall, answer (RAG), and summarization endpoints. The v0.2.4 release introduces **v2 response models**, a new in-place edit command, and several **security hardening fixes** that affect cross-agent authorization, upload path traversal, and secret leakage from the UI config endpoint.

## Memory Data Model

Memanto classifies every memory into one of **13 semantic types**, declared as a `Literal` in [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py). The `VALID_MEMORY_TYPES` set is used at runtime to validate writes; mismatched types are rejected before reaching the vector store.

| Type | Purpose |
|------|---------|
| `fact` | Verified information, project status, established truths |
| `preference` | User/entity preferences for personalization |
| `instruction` | Standing rules, constraints, and guidelines |
| `decision` | Architectural choices and rationale |
| `event` | Conversations, milestones, temporal occurrences |
| `goal` | Objectives and tracked milestones |
| `commitment` | Promises, obligations, TODOs |
| `observation` | Patterns and behavioral notes |
| `learning` | Knowledge acquired from experience |
| `relationship` | Entity connections and team context |
| `context` | Session summaries and conversation state |
| `artifact` | Tool outputs, files, and external references |
| `error` | Recorded failures and corrections |

Every record carries a `MemoryRecord` shape (defined under [memanto/app/models/__init__.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/models/__init__.py)) with fields for `type`, `title`, `content`, `scope_type`, `scope_id`, `actor_id`, `source`, `source_ref`, `confidence`, `tags`, and an optional TTL set via `memory.set_ttl(ttl_seconds)` inside the legacy write route.

Lifecycle state is one of four `StatusType` literals (`active`, `superseded`, `deleted`, `provisional`), and provenance is captured by six `ProvenanceType` values (`explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`). The constant `ALLOWED_UPDATE_FIELDS` in [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py) restricts which fields the new `memanto edit` command can mutate in place.

## Backend Services

The HTTP layer is thin: each route delegates to a dedicated service.

- **MemoryWriteService** — invoked by the legacy `/memory/write` and `/memory/batch/write` routes. It stores records into a Moorcheh namespace and embeds the `user_confirmed` flag into the call context, as visible in [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py).
- **MemoryExportService** — defined in [memanto/app/services/memory_export_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/memory_export_service.py), it walks `MEMORY_TYPE_ORDER`, queries each type, and emits a structured `memory.md`. The metadata table `MEMORY_TYPE_META` provides a human label and description for every type.
- **DailyAnalysisService** — in [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py), it consolidates session JSON, runs `client.answer.generate` with `SUMMARY_MODEL`, and writes a Markdown report to `~/.memanto/summaries/`. It then calls `SummaryVisualizationService.append_visualizations_to_summary` for charts (warnings are logged but do not fail the run).
- **ConversationMemoryExtractionService** — [memanto/app/services/conversation_memory_extraction_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/conversation_memory_extraction_service.py) bounds input to `MAX_MESSAGES=200`, `MAX_MEMORIES=100`, and `MAX_CONTENT_CHARS=12_000`, then drives Moorcheh's `answer.generate` with a constrained JSON header/footer prompt to extract typed candidates.
- **ContextSummarizationService** — [memanto/app/legacy/context_summarization_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/context_summarization_service.py) summarizes by scope or by ID list, and writes a `context`-typed memory with tags `["summary", "ai-generated", "custom"]`. The `compress_conversation_history` helper keeps `keep_recent_count` recent memories intact and compresses older context.

The CLI client in [memanto/cli/client/direct_client.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/client/direct_client.py) surfaces the same primitives; `_memory_md` queries all 13 types and hands them to the export service, defaulting to `~/.memanto/exports/{agent_id}_memory.md`.

## REST API (v2) Surface

The v2 router in [memanto/app/routes/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/routes/memory.py) exposes:

- `POST /answer` — RAG answer grounded in a namespace. Calls `client.answer.generate` with `kiosk_mode`; when kiosk mode is on, `threshold` defaults to `0.15` if the caller omitted it. The response carries `agent_id`, `session_id`, `question`, `answer`, `sources`, and `namespace`.
- `POST /daily-summary` — accepts a `DailySummaryRequest` with an optional `date` (YYYY-MM-DD) and `output_path`.
- Legacy `POST /memory/write`, `POST /memory/batch/write`, and `POST /memory/recall` (in [memanto/app/legacy/memory.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/legacy/memory.py)) — the batch route caps at 100 memories per request and pre-checks scope consistency.

```mermaid
flowchart LR
    Client[Agent / SDK] --> Route[FastAPI route<br/>v2 or legacy]
    Route --> Service[Backend service<br/>write / export / extract / summarize]
    Service --> Moorcheh[(Moorcheh namespace<br/>vector store + answer LLM)]
    Moorcheh --> Service
    Service --> Response[V2 response model<br/>typed memory or sources]
    Response --> Client
```

Request models defined in [memanto/app/models/__init__.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/models/__init__.py) include `MemoryAnswerRequest`, `ContextSummarizationRequest`, `CustomSummarizationRequest`, and `ConversationCompressionRequest`; response models use `MemoryResponse` plus the new v2 envelopes introduced in v0.2.4.

## v0.2.4 Security Hardening, SDK & CLI Updates

The v0.2.4 release adds three security fixes that interact directly with the memory routes:

1. **Cross-agent authorization** — write/recall/edit requests now verify that the caller's `agent_id` matches the resolved session's owner before any mutation or query is dispatched. This closes a path where one agent could read or overwrite another agent's namespace.
2. **Upload path-traversal protection** — file and artifact uploads validate the resolved path against an allow-list root before being written, preventing `../` escapes from leaking memory files outside the configured storage directory.
3. **Secret leakage in the UI config endpoint** — the config endpoint now redacts API keys and namespace tokens before returning the bootstrap payload consumed by the dashboard.

In addition, the official TypeScript SDK ([sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json), `@moorcheh-ai/memanto`, Node ≥ 20) ships OpenAPI-generated types that mirror the v2 response models, plus lifecycle hooks so agents can subscribe to memory write and recall events. On the CLI side, the new `memanto edit` command uses `ALLOWED_UPDATE_FIELDS` to perform in-place memory updates without round-tripping through a delete-and-rewrite cycle.

## See Also

- [TypeScript SDK (`@moorcheh-ai/memanto`)](https://github.com/moorcheh-ai/memanto/tree/main/sdks/typescript)
- [MCP Server integration](https://github.com/moorcheh-ai/memanto/tree/main/integrations/mcp)
- [Hermes Agents plugin](https://github.com/moorcheh-ai/memanto/tree/main/integrations/hermes-agents)
- [CrewAI integration](https://github.com/moorcheh-ai/memanto/tree/main/integrations/crewai)
- [LangGraph examples](https://github.com/moorcheh-ai/memanto/tree/main/examples/langgraph-memanto)
- [Research paper (arXiv:2604.22085)](https://arxiv.org/abs/2604.22085)

---

<a id='page-4'></a>

## Deployment, Configuration & Operations

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [CLI Commands, TypeScript SDK & Agent Integrations](#page-2), [Memory Model, Backend Services & REST API (v2)](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [memanto/app/config.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/config.py)
- [memanto/cli/config/manager.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/config/manager.py)
- [memanto/cli/commands/config_cmd.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/config_cmd.py)
- [memanto/cli/commands/schedule.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/schedule.py)
- [memanto/cli/schedule_manager.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/schedule_manager.py)
- [memanto/cli/migrate/runner.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/migrate/runner.py)
- [memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py)
- [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py)
- [sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)
</details>

# Deployment, Configuration & Operations

## Overview

Memanto is a typed semantic memory service designed for long-horizon AI agents. Its operational surface spans three coordinated layers: a Python application server (FastAPI), a CLI client used for administration and migration, and a TypeScript SDK published as `@moorcheh-ai/memanto` ([README.md](https://github.com/moorcheh-ai/memanto/blob/main/README.md)). Configuring and operating Memanto requires understanding how configuration flows from the CLI into the backend, how scheduled jobs are persisted, and how agents are deployed and migrated across providers.

The community release notes for v0.2.4 highlight several operational concerns that this page reflects: an official TypeScript SDK with lifecycle hooks, a new `memanto edit` command for in-place memory updates, v2 memory route response models, and security hardening covering cross-agent authorization, upload path-traversal, and secret leakage in the UI config endpoint.

## Configuration System

Memanto exposes a layered configuration model. The backend reads its settings from a Pydantic-managed config module ([memanto/app/config.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/config.py)), while the CLI maintains a separate, user-scoped configuration store managed through `ConfigManager` ([memanto/cli/config/manager.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/config/manager.py)) and surfaced via the `memanto config` subcommand ([memanto/cli/commands/config_cmd.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/config_cmd.py)).

The application's `settings` object centralizes values such as `SUMMARY_MODEL` (used by `daily_analysis_service.py`) and any operational flags passed into services. The CLI `ConfigManager` reads, writes, and persists per-user configuration (API keys, default agents, namespace preferences) to disk so subsequent invocations of `memanto ...` commands reuse the same context.

### Configuration Constants

Memanto enforces a closed-set vocabulary across several dimensions to prevent drift between the CLI, the SDK, and the backend.

| Dimension | Allowed Values | Source |
|-----------|----------------|--------|
| Memory types | `instruction`, `fact`, `decision`, `goal`, `commitment`, `preference`, `relationship`, `context`, `event`, `learning`, `observation`, `artifact`, `error` | [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py) |
| Provenance types | `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported` | [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py) |
| Updateable fields | `title`, `content`, `type`, `confidence`, `tags`, `source` | [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py) |
| Agent patterns | `support`, `project`, `tool` | [memanto/app/constants.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/constants.py) |

These constants gate writes from both the `SdkClient` and the FastAPI routes — the v2 memory route response models introduced in v0.2.4 validate incoming payloads against them.

## CLI Operations & Scheduling

The CLI is the primary operational interface for day-to-day administration. Beyond `memanto config`, the `memanto` command tree exposes scheduling and migration subsystems. The scheduler is implemented in [memanto/cli/schedule_manager.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/schedule_manager.py) and registered as a subcommand group in [memanto/cli/commands/schedule.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/schedule.py).

```mermaid
flowchart LR
  A[CLI User] --> B[memanto config]
  A --> C[memanto schedule]
  A --> D[memanto migrate]
  A --> E[memanto edit]
  B --> F[(ConfigManager<br/>~/.memanto/config)]
  C --> G[(ScheduleManager<br/>~/.memanto/schedules)]
  D --> H[Migration Runner]
  E --> I[SDK Client<br/>PUT /v2/memories/:id]
  G --> J[Scheduled Job]
  J --> K[Daily Analysis Service]
  K --> L[(Summary MD<br/>~/.memanto/summaries)]
```

Scheduled jobs typically invoke the daily analysis service, which reads session files, calls the LLM for summarization, and writes a Markdown report (see [memanto/app/services/daily_analysis_service.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/app/services/daily_analysis_service.py)). The scheduler persists jobs on disk so they survive CLI restarts; the `ScheduleManager` is responsible for registration, listing, and removal.

The `memanto edit` command added in v0.2.4 issues an in-place update against the v2 memory route, mutating only the fields enumerated in `ALLOWED_UPDATE_FIELDS`. This prevents callers from overwriting system-managed attributes such as `agent_id` or `created_at`.

## Deployment & Migration

Memanto can be deployed in two primary ways:

1. **As a hosted service** accessed via the Moorcheh API key — the default path for most users. The CLI and both SDKs read the key from environment variables or the `ConfigManager` and authenticate against the central backend.
2. **Embedded via SDK** — the TypeScript SDK requires `node >= 20` ([sdks/typescript/package.json](https://github.com/moorcheh-ai/memanto/blob/main/sdks/typescript/package.json)) and is built with `tsup`, tested with `vitest`, and ships OpenAPI-generated types plus lifecycle hooks. The Python SDK follows the same authentication model.

For organizations moving from competing memory providers, the migration subsystem is exposed through `memanto migrate` ([memanto/cli/commands/migrate.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/commands/migrate.py)) and orchestrated by [memanto/cli/migrate/runner.py](https://github.com/moorcheh-ai/memanto/blob/main/memanto/cli/migrate/runner.py). The runner supports three providers (Letta, mem0, Supermemory), each registered in a `_PROVIDER_BUNDLES` dictionary that pairs `export`, `compare`, and `report` helpers per provider. Typical flow:

- `run_<provider>_export` — pulls source memories into a normalized export.
- `load_export` / `write_preview` — previews what would land in Memanto.
- `run_migration` — executes the transfer through the SDK client.
- `compute_<provider>_metrics` and `build_<provider>_report_markdown` — produce a comparison report.

For IDE-style integrations, `memanto connect cursor` writes rule and skill files (e.g. `.cursor/rules/memanto.mdc`) that point Cursor at the same namespace used by SDK clients ([integrations/crewai/README.md](https://github.com/moorcheh-ai/memanto/blob/main/integrations/crewai/README.md)).

### Security Operations

The v0.2.4 release closes three operational security holes: cross-agent authorization (agents can no longer read or mutate other agents' memories), upload path-traversal (file uploads are sandboxed under an agent-scoped directory), and secret leakage in the UI config endpoint (sensitive fields are redacted before being returned). Operators upgrading should rotate any API keys previously logged by debug tooling.

## See Also

- [Memory Types & Taxonomy](memory-types.md)
- [SDK Reference (Python & TypeScript)](sdk-reference.md)
- [Migration Guide](migration-guide.md)
- [Hermes Plugin Integration](../integrations/hermes-agents/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: moorcheh-ai/memanto

Summary: Found 10 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

## 1. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/moorcheh-ai/memanto/issues/639

## 2. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/moorcheh-ai/memanto/issues/770

## 3. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/moorcheh-ai/memanto

## 4. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/moorcheh-ai/memanto

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/moorcheh-ai/memanto

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/moorcheh-ai/memanto

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/moorcheh-ai/memanto

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/moorcheh-ai/memanto/issues/1329

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/moorcheh-ai/memanto

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/moorcheh-ai/memanto

<!-- canonical_name: moorcheh-ai/memanto; human_manual_source: deepwiki_human_wiki -->