annal (Heyhayes)

MCPAI代理

提供方 heyhayes

AI代理 stdio · 本地进程 会话登录 社区 / 第三方 Claude
查看接入方式

Annal是一个为AI团队设计的语义记忆服务器,支持跨会话的知识存储、搜索和检索,适用于需要共享机构记忆的多代理工作流。

一句话选型结论

按资料字段整理

annal (Heyhayes) 属于AI代理类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 12 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量12暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

语义记忆Python本地部署AI代理知识管理向量数据库多代理协作

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
pip install annal

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 12 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 12 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
annal (Heyhayes)当前 12 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方heyhayes上游标注的维护方 heyhayes
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

12.6 KB
来自项目仓库与上游目录的原文,未做删改

Annal

A tool built by tools, for tools.

> Alpha — actively developed and used in production by the author across multiple projects. APIs and storage schemas are stabilising but may still change between minor versions. Bug reports and feedback welcome via issues.

Semantic memory server for AI agent teams. Stores, searches, and retrieves knowledge across sessions using pluggable vector backends (ChromaDB or Qdrant) with local ONNX embeddings, exposed as an MCP server.

Designed for multi-agent workflows where analysts, architects, developers, and reviewers need shared institutional memory — decisions made months ago surface automatically when relevant, preventing contradictions and preserving context that no single session can hold.

How it works

Annal runs as a persistent MCP server (stdio or HTTP) and provides tools for storing, searching, updating, and managing memories. Memories are embedded locally using all-MiniLM-L6-v2 (ONNX) and stored in a vector backend (ChromaDB by default, Qdrant optional), namespaced per project. When using Qdrant, hybrid search combines dense vector similarity with BM25 keyword matching via reciprocal rank fusion for better recall.

File indexing is optional. Point Annal at directories to watch and it will chunk markdown files by heading, track modification times for incremental re-indexing, and keep the store current via watchdog filesystem events. For large repos, file watching can be disabled per-project — agents trigger re-indexing on demand via index_files.

Indexing is non-blocking. init_project and index_files return immediately while reconciliation runs in the background. Agents poll index_status to track progress, which shows elapsed time and chunk counts.

Agent memories and file-indexed content coexist in the same search space but are distinguished by tags (memory, decision, pattern, bug, indexed, etc.), so agents can search everything or filter to just what they need.

A web dashboard (HTMX + Jinja2) runs alongside the server, providing a browser-based view of memories with search, browsing, bulk delete, and live SSE updates when memories are stored or indexing is in progress.

Quick start```bash

pip install annal

One-shot setup: creates service, configures MCP clients, starts the daemon

annal install


Or from source:```bash
git clone https://github.com/heyhayes/annal.git
cd annal
pip install -e ".[dev]"

# Run in stdio mode (single session)
annal

# Run as HTTP daemon (shared across sessions)
annal --transport streamable-http

annal install detects your OS and sets up the appropriate service (systemd on Linux, launchd on macOS, scheduled task on Windows). It also writes MCP client configs for Claude Code, Codex, and Gemini CLI.

MCP client integration

Claude Code

Add to ~/.mcp.json for stdio mode:```json
{
"mcpServers": {
"annal": {
"command": "/path/to/annal/.venv/bin/annal"
}
}
}


For HTTP daemon mode (recommended when running multiple concurrent sessions):```json
{
"mcpServers": {
"annal": {
"type": "http",
"url": "http://localhost:9200/mcp"
}
}
}

Codex / Gemini CLI

annal install writes the appropriate config files automatically. See annal install output for paths.

Agent configuration

For agents to actually use Annal, they need instructions that explain why it matters, not just how to call it. Add one of these snippets to your CLAUDE.md, AGENT.md, or equivalent agent instructions file.

Recommended snippet```xml

You have persistent semantic memory via Annal (mcp__annal__* tools). Memories survive across
sessions and are searchable by meaning. This is your long-term memory — MEMORY.md is a cheat
sheet, Annal is deep storage.

Why this matters: every session starts blank. Without Annal, you repeat investigations,
rediscover patterns, and miss prior decisions. With it, you inherit your past self's
understanding of the codebase.

When to search (use mode="probe" to scan, then expand_memories for details):
- Session start: load context for the current task area
- Unfamiliar code: before diving into a module you haven't seen this session
- "What happened" questions: anything about recent work, prior decisions, project state
- Before architectural changes: check for prior decisions in the same domain
- Familiar-feeling bugs: search for prior root causes

When to store (tag with type + domain, e.g. tags=["decision", "auth"]):
- Bug root causes and the fix that worked
- Architectural decisions and their rationale
- Codebase patterns that took effort to discover
- User preferences for workflow, tools, style
- Key file paths and module responsibilities in unfamiliar codebases

After completing a task, before moving on, always ask: what did I learn that I'd want to know
next time? If you discovered a root cause, mapped unfamiliar architecture, or found a pattern
that took effort — store it. This is the single most important habit for cross-session value.

Project name: use the basename of the current working directory.


### Minimal snippet

If you prefer something shorter:```xml

You have persistent semantic memory via Annal (mcp__annal__* tools). Unlike MEMORY.md which
resets with context, Annal memories survive across sessions and are searchable by meaning.

This matters because you lose all context when a session ends. Annal is how you recover it.
Search before starting work — your past self may have already mapped the architecture,
debugged this module, or recorded a decision that saves you from repeating the investigation.

Search: at session start, when touching unfamiliar code, when the user asks "what did we
decide about X", and before proposing architectural changes. Use mode="probe" to scan cheaply.

Store: bug root causes, architectural decisions, codebase patterns, surprising discoveries —
anything you'd want to know if you started a fresh session tomorrow. Tag with a type
(decision, bug, pattern, memory) plus domain tags. After completing a task, always ask: what
did I learn? Store it before moving on.

Project name: use the basename of the current working directory.

Project setup

On first use, call init_project with watch paths for file indexing, or just start storing memories — unknown projects are auto-registered in the config.```
init_project(project_name="myapp", watch_paths=["/home/user/projects/myapp"])


Every tool takes a `project` parameter. Use the directory name of the codebase you're working in (e.g. "myapp", "annal").

## Tools

`store_memory` — Store knowledge with tags and source attribution. Near-duplicates (>95% similarity) are automatically skipped. When a similar memory is found (80-95% similarity), a hint suggests using the `supersedes` parameter to replace it. Pass `supersedes=` to mark the old memory as replaced — it drops out of search but remains for audit.

`store_batch` — Store multiple memories in a single call. Each item takes the same fields as `store_memory` (`content`, `tags`, `source`, `supersedes`). More efficient than repeated `store_memory` when storing 2+ memories at once.

`search_memories` — Natural language search with optional tag filtering and similarity scores. Three output modes: `mode="summary"` (default) returns first 200 chars with metadata, `mode="probe"` returns compact one-line summaries for scanning large result sets, and `mode="full"` returns complete content. Optional `min_score` filter suppresses low-relevance noise. Tags use fuzzy matching (semantic similarity) so `tags=["auth"]` finds memories tagged `authentication`. Temporal filtering with `after` and `before` (ISO 8601 dates) scopes results by creation date. Optional `projects` parameter enables cross-project search (`projects="*"` searches all configured projects). Pass `include_superseded=True` to surface replaced memories. Returned results include `hit_count` and `last_accessed_at` for access tracking.

`expand_memories` — Retrieve full content for specific memory IDs. Use after a probe search to fetch details for relevant results.

`update_memory` — Revise content, tags, or source on an existing memory without losing its ID or creation timestamp. Tracks `updated_at` alongside the original.

`retag_memory` — Modify tags on an existing memory without changing content. Supports `add_tags`/`remove_tags` for incremental edits, or `set_tags` to replace all tags at once.

`delete_memory` — Remove a specific memory by ID.

`prune_stale` — Review and delete stale agent memories. Identifies memories with `last_accessed_at` older than `max_age_days` (default 60) and optionally those never accessed. Runs in `dry_run=True` mode by default, returning a summary of what would be deleted. Set `dry_run=False` to execute deletion. Only targets agent memories — file-indexed chunks are managed by the file watcher.

`list_topics` — Show all tags and their frequency counts.

`init_project` — Register a project with watch paths, patterns, and exclusions for file indexing. Indexing starts in the background and returns immediately.

`index_files` — Full re-index: clears all file-indexed chunks and re-indexes from scratch. Use after changing exclude patterns to remove stale chunks.

`index_status` — Per-project diagnostics: total chunks, file-indexed vs agent memory counts, stale and never-accessed memory counts, indexing state with elapsed time, and last reconcile timestamp.

## Configuration

`~/.annal/config.yaml`:```yaml
data_dir: ~/.annal/data
port: 9200
projects:
myapp:
watch_paths:
- /home/user/projects/myapp
watch_patterns:
- "**/*.md"
- "**/*.yaml"
- "**/*.toml"
- "**/*.json"
watch_exclude:
- "**/node_modules/**"
- "**/vendor/**"
- "**/.git/**"
- "**/.venv/**"
- "**/__pycache__/**"
- "**/dist/**"
- "**/build/**"
large-repo:
watch: false          # disable file watching, use index_files on demand
watch_paths:
- /home/user/projects/large-repo

Backend configuration

By default, Annal uses ChromaDB (local, file-based, no extra dependencies). To switch to Qdrant for native tag filtering, hybrid BM25+vector search, and concurrent write support, add a storage section:```yaml
storage:
backend: qdrant
backends:
qdrant:
url: http://localhost:6333
hybrid: true # enable BM25 sparse vectors (default: true)
chromadb:
path: ~/.annal/data # kept for migration


Install the Qdrant client dependency: `pip install annal[qdrant]`

To migrate existing data between backends: `annal migrate --from chromadb --to qdrant --project myapp`

### Export / Import

Back up and restore memories as JSONL:```bash
annal export --project myapp > backup.jsonl
annal import --project myapp backup.jsonl

Running as a daemon

The recommended approach is annal install, which sets up the service for your OS automatically.

For manual setup, use the service scripts in contrib/:

Linux (systemd)```bash

cp contrib/annal.service ~/.config/systemd/user/

Edit ExecStart path, then:

systemctl --user daemon-reload
systemctl --user enable --now annal


### macOS (launchd)```bash
cp contrib/com.annal.server.plist ~/Library/LaunchAgents/
# Edit the ProgramArguments path, then:
launchctl load ~/Library/LaunchAgents/com.annal.server.plist

Windows (scheduled task)```powershell

.\contrib\annal-service.ps1 -Action install -AnnalPath "C:\path\to\annal.venv\Scripts\annal.exe"
Start-ScheduledTask -TaskName "Annal MCP Server"


## Dashboard

When running as an HTTP daemon, the dashboard is available at `http://localhost:9200`. It provides a terminal-inspired interface for browsing and managing memories across all projects.

The landing page features a command palette for quick navigation, a stats ribbon that expands to show per-project breakdowns when clicked, and a live activity feed with SSE updates as memories are stored, deleted, or indexing runs.

The memories view provides browsing with pagination and filters (by type, source, tags), semantic search with cross-project support, expandable content previews, bulk delete by selection or filter, a "Show superseded" toggle for viewing replaced memories, and a "Show stale only" filter that surfaces memories not accessed in 60+ days.

The projects page shows all registered projects with memory counts broken down by type, stale counts, and top tags rendered as clickable pills that jump to filtered memory views.

Disable with `--no-dashboard` if not needed.

## Changelog

See CHANGELOG.md for release history.

## Development```bash
pip install -e ".[dev]"
pytest -v

275 tests cover store operations, search, hit tracking, stale detection, supersession, batch storage, indexing, file watching, dashboard routes, SSE events, CLI installation, export/import, migration, and a shared backend conformance suite that runs against both ChromaDB and Qdrant.

License

MIT — see LICENSE.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
annal (Heyhayes) 怎么安装?

在客户端按下面的安装命令接入:pip install annal。装完在客户端配置里引用同一个包或端点。

annal (Heyhayes) 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

annal (Heyhayes) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

annal (Heyhayes) 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

annal (Heyhayes) 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

annal (Heyhayes) 能提供哪些能力?

资料显示约 12 个工具;能力标签包括 多代理协作、Python、Claude、向量数据库。具体工具清单以官方文档为准。

annal (Heyhayes) 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

annal (Heyhayes) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。