Agentic Memory Layer (MCP server)

Run the Obsidian-backed MCP server that gives Artemis City agents a persistent, versioned memory bus.

The Artemis Agentic Memory Layer is a Model Context Protocol (MCP) server that exposes an Obsidian vault to agents over a small, authenticated REST API. It lets agents read, write, search, tag, and reorganize notes as a shared, versioned source of truth — the long-term memory bus for Artemis City.

Use this integration when you want agents to:

• Persist context, plans, or reflections across sessions.
• Coordinate with other agents around a single knowledge store.
• Read structured human-curated notes (instructions, personas, capability docs) at runtime.
• Maintain a queryable graph of tasks, tags, and frontmatter metadata.

The Python-side client and trust-aware wrapper that calls this server are documented in Memory Integration. This page documents the MCP server itself: how to deploy it, how to configure it, and the endpoints it exposes.

How it fits

┌─────────────────┐   HTTPS + Bearer   ┌──────────────────────┐   Local REST   ┌───────────────┐
│ Artemis agents  │ ─────────────────▶ │  Agentic Memory MCP  │ ─────────────▶ │ Obsidian vault│
│ (Python / LLM)  │ ◀───────────────── │       server         │ ◀───────────── │  + REST plugin│
└─────────────────┘   JSON responses   └──────────────────────┘                └───────────────┘

The MCP server is a thin translation layer. It accepts MCP-style tool invocations over HTTP, authenticates them against a shared key, and forwards them to the Obsidian Local REST API plugin running on the host vault.

Prerequisites

• Node.js 18+ (or Docker) on the host running the MCP server.
• Obsidian with the Local REST API community plugin installed and enabled.
• An API key generated from the Local REST API plugin settings.
• A second secret (MCP_API_KEY) that agents present when calling this server.

Configuration

The server reads configuration from environment variables (typically a .env file or the environment: block in docker-compose.yml).

Variable	Required	Default	Description
MCP_API_KEY	Yes	—	Shared secret agents send as Authorization: Bearer <key>.
OBSIDIAN_BASE_URL	Yes	—	URL of the Obsidian Local REST API (for example https://127.0.0.1:27124).
OBSIDIAN_API_KEY	Yes	—	API key from the Obsidian Local REST API plugin.
PORT	No	3000	Port the MCP server listens on.
MCP_LOG_LEVEL	No	info	One of debug, info, warn, error.

The server exits on startup if MCP_API_KEY, OBSIDIAN_BASE_URL, or OBSIDIAN_API_KEY is missing.

OBSIDIAN_BASE_URL by environment

Environment	Value
MCP server on the host, Obsidian on the host	https://127.0.0.1:27124
MCP server in Docker, Obsidian on host (macOS / Windows)	https://host.docker.internal:27124
MCP server in Docker, Obsidian on host (Linux)	https://<host-ip>:27124 or use network_mode: host

Replace 27124 with the port shown in your Local REST API plugin settings.

Deployment

Docker (recommended)

Use the bundled docker-compose.yml to build and run the server:

docker-compose up --build

The server is then reachable at http://localhost:3000 and forwards requests to your vault at OBSIDIAN_BASE_URL.

Local Node.js

npm install
npm run dev      # hot-reload, development
# or
npm run build && npm start   # production build

Health check

The server exposes an unauthenticated health endpoint:

curl http://localhost:3000/health
# {"status":"ok"}

Authentication

Every /api/* request must include the bearer token:

Authorization: Bearer <MCP_API_KEY>

Missing or mismatched tokens return 403 Forbidden. Combine this with Trust-Based Access Control on the client side so agent-level trust scores gate which operations are even attempted.

API endpoints

All endpoints are POST, accept application/json, and live under /api. Responses use a consistent envelope:

{ "success": true, "data": { ... } }

or, on failure:

{ "success": false, "error": "..." }

Endpoint	Body fields	Purpose
/api/getContext	path	Read the full content of a note.
/api/appendContext	path, content	Append content to a note (creates it if missing).
/api/updateNote	path, content	Replace the entire body of a note.
/api/searchNotes	query	Full-text search across the vault.
/api/listNotes	(none)	List all note paths in the vault.
/api/deleteNote	path	Delete a note.
/api/manageFrontmatter	path, key, value	Upsert a YAML frontmatter key.
/api/manageTags	path, tags[], action (add or remove)	Add or remove tags.
/api/searchReplace	path, search, replace	In-place search and replace in a note.

Example: read a note

curl -X POST http://localhost:3000/api/getContext \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -d '{ "path": "Daily/2026-05-20.md" }'

{
  "success": true,
  "data": {
    "path": "Daily/2026-05-20.md",
    "content": "# Daily Notes\n\n- Reviewed agent reflections\n- ..."
  }
}

Example: append agent context

curl -X POST http://localhost:3000/api/appendContext \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -d '{
        "path": "Agents/artemis/journal.md",
        "content": "\n- 2026-05-20: Completed reflection cycle."
      }'

Example: tag a note

curl -X POST http://localhost:3000/api/manageTags \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -d '{ "path": "Projects/atp.md", "tags": ["urgent", "review"], "action": "add" }'

Calling the server from Python

Most Artemis agents talk to the memory layer through the Python MemoryClient, which wraps these endpoints and adds trust enforcement:

from memory.integration import MemoryClient

client = MemoryClient(
    base_url="http://localhost:3000",
    api_key="your_mcp_api_key",
)

# Read a note
response = client.get_context("Daily/2026-05-20.md")
if response.success:
    print(response.data["content"])

# Persist a reflection
client.store_agent_context(
    "artemis",
    "Completed ATP integration successfully",
)

See Memory Integration for the full client surface, trust levels, and context-loading helpers.

Security considerations

• Treat both keys as secrets. MCP_API_KEY grants full vault access via this server; OBSIDIAN_API_KEY grants direct vault access via the plugin.
• Default binding is localhost. If you expose the server to a wider network, put it behind a firewall, reverse proxy, or mTLS.
• Self-signed certificates. The server is configured to accept the plugin’s self-signed HTTPS cert (rejectUnauthorized: false). For production, terminate TLS at a trusted proxy.
• Validate agent inputs. The server performs minimal validation. Sanitize paths and content on the client side, and combine with trust scoring before issuing write or delete operations.

Troubleshooting

Symptom	Likely cause
Server exits on boot with … is not set	A required env var is missing. Check .env or the compose environment: block.
ECONNREFUSED from the server	Obsidian is closed, the Local REST API plugin is disabled, or OBSIDIAN_BASE_URL is wrong.
403 Forbidden: Invalid API Key	The agent’s Authorization header does not match MCP_API_KEY.
Unauthorized from Obsidian	OBSIDIAN_API_KEY is wrong or was rotated in the plugin settings.
Note operations fail	Path does not match the exact vault path (including the .md extension).

On Linux hosts running the MCP server in Docker, host.docker.internal does not resolve by default — use the host’s bridge IP (often 172.17.0.1) or set network_mode: host in compose.