HippoDid MCP Server
Persistent, structured cloud memory for AI agents. BYOK — bring your own AI key.
Open source Open in the app JSON README (API)
About
Persistent, structured cloud memory for AI agents. BYOK — bring your own AI key.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- snowmanjy
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.0
- Last push
- 2026-04-05T18:41:07Z
- Repository state
- ativo
- Language
- Java
- License
- Apache-2.0
- Added
- 2026-08-29 04:01:25
- Updated
- 2026-08-29 04:01:25
- Origin id
io.github.snowmanjy/hippodid-mcp-server
README
<!-- mcp-name: io.github.snowmanjy/hippodid-mcp-server -->
<p align="center">
<img src="docs/assets/hippodid-hero.png" alt="HippoDid MCP Server — persistent cloud memory for AI agents" width="780" />
</p>
<p align="center">
<strong>HippoDid MCP Server</strong><br/>
Persistent, portable memory for AI agents. Your AI forgets everything between sessions. HippoDid remembers.
</p>
---
# HippoDid MCP Server
MCP (Model Context Protocol) server for [HippoDid](https://hippodid.com) — connects Claude Code, Claude Desktop, ChatGPT, Gemini CLI, Codex CLI, Cursor, and any MCP-compatible client to persistent AI character memory.
## What is HippoDid?
HippoDid is a cloud memory infrastructure for AI agents. It stores structured memories (preferences, decisions, skills, relationships) in a searchable database and retrieves them across sessions, tools, and AI providers. Write a memory in Claude Code, recall it in ChatGPT. Switch from Cursor to Gemini — your agent's memory travels with it.
Key features:
- **Cross-platform memory** — same memories accessible from any MCP client or ChatGPT via OAuth
- **Structured extraction** — raw text is automatically parsed into categorized facts with salience scores
- **Temporal decay** — memories fade naturally by category (skills are evergreen, events fade in 14 days)
- **Character scoping** — each agent/project gets its own memory namespace
- **BYOK AI** — bring your own OpenAI, Anthropic, or Gemini key for extraction
## Quick Start
### 1. Get an API Key
Sign up at [hippodid.com](https://hippodid.com) and create an API key from your dashboard.
### 2. Download the JAR
Download the latest release from [GitHub Releases](https://github.com/SameThoughts/hippodid-mcp-server/releases).
### 3. Configure Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"hippodid": {
"command": "java",
"args": ["-jar", "/path/to/hippodid-mcp-server-1.1.0.jar"],
"env": {
"HIPPODID_API_KEY": "hd_key_your_key_here",
"HIPPODID_CHARACTER_ID": "your-character-uuid"
}
}
}
}
```
### 4. Start Using
Ask Claude to remember things, search memories, sync files, and more.
## MCP Tools
| Tool | Description |
|------|-------------|
| `create_character` | Create a new character to store memories for |
| `list_characters` | List all characters accessible to you |
| `add_memory` | Add a memory via the AUDN pipeline (rule-based salience + dedup) |
| `add_memory_direct` | Write a memory directly, bypassing AUDN pipeline (Starter+ tier) |
| `search_memories` | Hybrid semantic + keyword search across memories |
| `sync_file` | Sync a local file to the HippoDid cloud |
| `import_document` | Import a document and extract memories (Starter+ tier) |
| `list_synced_files` | List files synced to the cloud for a character |
| `get_sync_status` | Get sync status summary for a character |
| `export_character` | Export all memories for a character as Markdown |
| `add_watch_path` | Sync a file and register the path for background tracking |
| `list_watch_paths` | List all watched file paths in this session |
| `force_sync` | Force an immediate sync of all watched paths |
| `configure_ai` | Configure tenant BYOK AI providers |
| `test_ai_config` | Test connectivity of saved AI provider configuration |
## Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `HIPPODID_API_KEY` | Yes | — | Your HippoDid API key |
| `HIPPODID_CHARACTER_ID` | No | — | Default character UUID for background sync |
| `HIPPODID_BASE_URL` | No | `https://api.hippodid.com` | API base URL |
| `MCP_SYNC_INTERVAL` | No | `300` | Background sync interval in seconds |
| `MCP_AUTO_CAPTURE` | No | `false` | Disable background watcher (AI handles sync) |
| `MCP_AUTO_RECALL` | No | `false` | Disable background hydration (AI handles download) |
| `MCP_RECALL_CACHE_TTL` | No | `120` | Search result cache TTL in seconds |
## Architecture
```
Claude Desktop → stdio (JSON-RPC) → McpServerRunner → HippoDidClient → HTTP → HippoDid REST API
```
The MCP server uses the [hippodid-spring-boot-starter](https://github.com/SameThoughts/hippodid-spring-boot-starter) to communicate with the HippoDid REST API over HTTP. All authentication and tenant isolation is handled server-side via Bearer tokens.
## Building from Source
Requires Java 21+ and Maven 3.8+.
```bash
mvn clean package -DskipTests
java -jar target/hippodid-mcp-server-1.1.0.jar
```
## Versioning
The MCP server version matches the [hippodid-spring-boot-starter](https://github.com/SameThoughts/hippodid-spring-boot-starter) version. Both must be at the same version for compatibility.
## License
Apache License 2.0 — see [LICENSE](LICENSE).