Hermes Agent Memory: Add a Readable Project Wiki with MCP

Hermes Agent already has persistent memory: compact Markdown notes, a user profile, searchable session history, and an optional external memory provider. That is a strong personal-memory stack. But a long-lived software project needs a different contract. Its decisions, runbooks, sources, and corrections should be files your team can read, edit, and self-host—not facts available only through an embeddings API.

The useful architecture is not “replace Hermes memory.” It is separate personal memory from project knowledge. Keep preferences and environment facts in Hermes; connect a shared project wiki through MCP. Meshnote provides that second layer as linked Markdown pages that Hermes and other MCP clients can maintain.

What Hermes Agent remembers natively

Hermes loads two bounded files from the active profile: MEMORY.md for durable agent notes and USER.md for user preferences. The current documented defaults cap them at 2,200 and 1,375 characters. They are injected at session start, so retrieval is unnecessary, but edits made during a session appear in the prompt on the next session. Hermes also keeps session history in SQLite and supports full-text search across prior conversations.

An optional provider adds deeper recall. Hermes currently documents eight bundled choices, including Mem0, Hindsight, Honcho, OpenViking, Holographic, RetainDB, ByteRover, and Supermemory. One external provider can be active at a time, alongside built-in memory. Before choosing one, read the broader production architecture for persistent LLM memory.

This stack is suited to “the user prefers concise output” or “this machine uses WSL2.” It should not be the only source of truth for “production deploys must pass a readiness check” or “ADR-014 replaced Redis with PostgreSQL.” Those claims need structure, provenance, correction history, and access from tools other than one Hermes profile.

The missing boundary: identity memory versus project memory

Knowledge	Best home	Reason
User preference or stable workstation fact	Hermes `USER.md` / `MEMORY.md`	Small and always visible
Past conversation detail	Hermes session search	Retains evidence without bloating every prompt
Automatically extracted personal history	Hermes memory provider	Semantic, graph, or modeled recall at larger scale
Architecture decision, runbook, research note, source	Shared Markdown wiki over MCP	Readable, reviewable, portable, and tool-agnostic
Temporary plan and tool output	Current session	Most execution detail should expire

This boundary prevents two common failures. First, project truth does not disappear when you switch profiles, agents, or vendors. Second, personal recall does not become a noisy dump of every repository detail. The same pattern supports shared memory across AI tools: Hermes can write a decision today, and another MCP client can read the same page tomorrow.

Runnable setup: connect Hermes to Meshnote with OAuth

Hermes includes MCP support in its standard installation. Meshnote exposes a remote Streamable HTTP endpoint and OAuth 2.1 with PKCE, so you do not need to paste an API key into config.yaml.

Add the server from a terminal on the machine running Hermes:
```
hermes mcp add --url https://meshnote.io/mcp --auth oauth meshnote
```
Hermes discovers OAuth metadata, opens a browser for authorization, and stores the token separately under the active profile's MCP token directory.
Test discovery before depending on the connection:
```
hermes mcp test meshnote
```
A successful test should list Meshnote tools such as list_projects, read_page, search_wiki, write_page, and append_log.
Start Hermes and create a scoped project:
```
hermes chat
```
Then ask: “Use Meshnote to create a KnowledgeBase project named Acme Platform. Read its schema and index before writing anything.” Reading the project schema first matters because each wiki can define its own page structure and operating rules.

Give Hermes an explicit promotion contract:

For this project, store only durable decisions, verified procedures,
source-backed research, and reusable handoffs in Meshnote.
Do not store raw chat, secrets, credentials, speculative claims,
or transient task output. Search before writing. Correct an existing
page instead of creating a competing fact. Append a short log entry
for substantive changes.

If you prefer declarative configuration, the equivalent entry in ~/.hermes/config.yaml is:

mcp_servers:
  meshnote:
    url: "https://meshnote.io/mcp"
    auth: oauth
    enabled: true
    timeout: 120

Run /reload-mcp after editing a live Hermes session. Each Hermes profile authenticates its own OAuth connection; do not assume credentials are shared across profiles.

A five-minute memory acceptance test

A connection test proves transport, not memory quality. Run this behavioral test before trusting the setup:

Write: ask Hermes to create decisions/api-versioning.md with the decision “Public endpoints use URL versioning,” its rationale, status, and today's date.
Restart: end the chat, start a new Hermes session, and ask which API versioning rule applies. Require Hermes to search Meshnote and cite the page path.
Correct: change the decision to header-based versioning. Ask Hermes to update the existing page, explain why it changed, and append a log entry.
Audit: use page history to confirm the old version remains recoverable and the current page contains only the new rule.
Handoff: connect another MCP-capable client to the same project and ask the same question. It should recover the corrected rule without access to the original Hermes conversation.

This correction-and-handoff drill is the element most Hermes memory overviews omit. Recall is useful; reconstructable current truth is what makes memory operational.

How the main options differ

Option	Best at	Trade-off
Hermes built-in memory	Compact preferences and environment facts that should always be visible	Tight capacity; profile-scoped rather than a full project knowledge system
Mem0	Automatic fact extraction plus semantic, keyword, entity, and temporal retrieval	Inferred facts and indexes are less directly reviewable than maintained documents; managed and self-operated modes differ
Zep / Graphiti	Evolving entities, relationships, provenance, and point-in-time queries	A temporal graph adds operational complexity when the real requirement is a small set of readable decisions
Letta	Stateful agents with always-visible memory blocks and searchable archival memory	Memory is closely coupled to the Letta agent runtime and its agent state model
Native ChatGPT or Claude memory	Low-setup personalization inside one product	Limited cross-tool authority and portability for team-owned project knowledge
Meshnote over MCP	Readable Markdown, explicit pages, history, backlinks, and cross-client project memory	Agents need a write policy; it does not automatically infer every personal preference

These are complementary choices, not a universal leaderboard. Mem0's April 2026 architecture emphasizes additive extraction and multi-signal retrieval. Graphiti models validity windows and preserves superseded relationships. Letta keeps selected blocks in context and uses semantic archival storage for colder facts. Benchmark scores across vendor reports are not directly comparable when models, retrieval budgets, datasets, and managed versus self-operated features differ. Test your own correction, isolation, provenance, and export requirements instead; the vector versus readable memory guide provides a storage-level framework.

Operating rules that keep the wiki useful

Search before write. Update the canonical page rather than producing near-duplicates.
Keep evidence beside claims. Link source documents or logs, and distinguish observation from conclusion.
Scope projects deliberately. Do not mix customer, personal, and company knowledge in one wiki.
Prefer correction over accumulation. Current pages should be unambiguous; history preserves what changed.
Promote selectively. A successful command is not automatically a reusable runbook.

The result is a layered system: Hermes retains the small facts that shape its behavior, while the project retains knowledge independently of any one agent. Meshnote is $8/month hosted, or self-hosted for teams from $10/seat/month with a five-seat minimum. Start syncing — $8/mo.