전체 문서 -- 가이드, 도구 참조, 아키텍처 및 유지 관리에 대한 내용은 cachorro.space에서 확인하세요.
Anthropic의 MCP Memory 서버를 위한 드롭인 대체제입니다. SQLite 지속성, 벡터 임베딩, 의미론적 검색, 그리고 동적 순위 지정을 위한 Limbic Scoring 기능을 제공합니다.
이유는 무엇인가요? 기존 서버는 모든 작업 시 전체 지식 그래프를 JSONL 파일에 기록하며, 잠금이나 원자적 쓰기 기능이 없습니다. 동시 접근(여러 MCP 클라이언트) 환경에서는 데이터 손상이 발생합니다. 이 서버는 이를 적절한 SQLite 데이터베이스로 대체합니다.
Anthropic의 8개 MCP 도구와 드롭인 호환 (동일한 API, 동일한 동작)
SQLite + WAL -- 안전한 동시 접근, 더 이상 손상된 JSONL 없음
sqlite-vec + ONNX 임베딩을 통한 의미론적 검색 (94개 이상의 언어 지원)
하이브리드 검색 (FTS5 + KNN) -- BM25 전체 텍스트 검색과 RRF(Reciprocal Rank Fusion)를 통한 의미론적 벡터 검색을 결합합니다. 정확한 용어나 의미론적 유사성, 또는 둘 다를 사용하여 엔티티를 찾습니다.
Limbic Scoring -- 중요도, 시간적 감쇠, 동시 발생 신호 및 하이브리드 검색 점수를 사용한 동적 재순위 지정. API에 투명하게 작동합니다.
의미론적 중복 제거 -- 코사인 유사도가 0.85 이상일 때 새로운 관찰에 대한 자동 similarity_flag (비대칭 텍스트 길이에 대한 포함 점수 포함)
통합 보고서 -- 분할 후보, 플래그 지정된 관찰, 오래된 엔티티 및 대형 엔티티에 대한 읽기 전용 상태 점검
향상된 최신성 감쇠 -- ALPHA_CONS=0.2 다일 통합 신호를 포함한 entity_access_log 추적
포함 수정 -- 중복 제거 점수 산정 시 비대칭 텍스트 길이(비율 >= 2.0)에 대한 적절한 처리
관찰 종류 -- 관찰의 의미론적 분류 (hallazgo, decision, estado, spec, metrica, metadata, generic)
관찰 대체 -- 명시적 교체 체인: 새로운 관찰이 이전 관찰을 대체할 수 있으며, 이전 관찰은 대체된 것으로 타임스탬프가 찍힙니다.
엔티티 상태 -- 수명 주기 추적: activo, pausado, completado, archivado (상태 인식 검색 디부스팅 포함)
관계 컨텍스트 + 유효 기간 -- 관계는 선택적 컨텍스트, active/ended_at 필드를 포함하여 시간적 유효성을 가집니다.
자동 역관계 -- contains/parte_de 쌍이 자동으로 생성됩니다.
성찰(Reflections) -- 독립적인 서사 계층: 엔티티/세션/관계/전역에 첨부된 자유 형식의 산문, 작성자 및 기분 메타데이터 포함, 의미론적 + FTS5 하이브리드 검색 가능
경량화 -- 유사 솔루션의 약 1.4GB 대비 총 약 500MB
마이그레이션 -- Anthropic의 JSONL 형식에서 원클릭 가져오기
제로 설정 -- 즉시 사용 가능; 임베딩 모델은 첫 사용 시 자동 다운로드됩니다.
Related MCP server: Mind Keg MCP
{
"mcpServers": {
"memory": {
"command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
}
}
}또는 로컬에서 복제 및 실행:
{
"mcpServers": {
"memory": {
"command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
}
}
}임베딩 모델(sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, 약 465MB, ONNX CPU, 384차원)은 의미론적 도구가 호출될 때 첫 사용 시 자동 다운로드됩니다. 수동 설정은 필요하지 않습니다.
미리 다운로드하려면 다음을 수행하세요:
cd /path/to/mcp-memory
uv run python scripts/download_model.py이것은 동일한 파일을 ~/.cache/mcp-memory-v2/models/로 다운로드하는 얇은 래퍼입니다. 모델이 없어도 의미론적이지 않은 모든 도구는 정상 작동하며, search_semantic만 사용할 수 없습니다.
Anthropic MCP Memory JSONL 파일이 있는 경우 migrate 도구를 사용하거나 직접 호출하세요:
uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"기능별로 그룹화된 총 19개 도구:
도구 | 설명 |
| 엔티티 생성 또는 업데이트 (충돌 시 관찰 병합). |
| 엔티티 간 유형화된 관계 생성. |
| 기존 엔티티에 관찰 추가. 의미론적 분류 및 명시적 교체를 위한 |
| 엔티티 및 모든 관계/관찰 삭제 |
| 엔티티에서 특정 관찰 삭제 |
| 엔티티 간 특정 관계 삭제 |
도구 | 설명 |
| 부분 문자열로 검색 (이름, 유형, 관찰 내용) |
| 이름으로 엔티티 검색. |
| Limbic Scoring 재순위 지정을 통한 벡터 임베딩 기반 의미론적 검색 |
도구 | 설명 |
| 엔티티 분할 필요 여부 분석 (의미론적 클러스터링 + TF-IDF 폴백) |
| 제안된 엔티티 이름 및 관계와 함께 분할 제안 |
| 승인된 분할 실행 (원자적 트랜잭션) |
| 분할이 필요한 모든 엔티티 찾기 |
| 엔티티 내 의미론적으로 중복된 관찰 찾기 (코사인 + 포함) |
| 읽기 전용 통합 보고서 생성 (분할 후보, 플래그 지정된 관찰, 오래된 엔티티) |
도구 | 설명 |
| Anthropic의 JSONL 형식에서 가져오기 (멱등성) |
|
|
도구 | 설명 |
| 엔티티, 세션, 관계 또는 전역에 서사적 성찰 추가. 작성자, 내용, 기분 허용. |
| 의미론적 + FTS5 하이브리드(RRF)를 통한 성찰 검색. 선택적 필터: 작성자, 기분, target_type. |
8가지 표준 유형:
유형 | 목적 |
| 장기 프로젝트 |
| 작업 세션 |
| 시스템 및 도구 |
| 아키텍처/기술적 결정 |
| 시간 제한 이벤트 |
| 사람 |
| 외부 리소스 |
| 기본 폴백 |
관찰에 대한 의미론적 분류:
종류 | 목적 |
| 발견 및 조사 결과 |
| 내려진 결정 |
| 상태 스냅샷 |
| 사양 및 요구 사항 |
| 정량적 측정 |
| 시스템 생성 메타데이터 |
| 기본 (분류 없음) |
관계 유형은 자유 형식입니다(제한적인 열거형 없음). 하드코딩된 유일한 역관계 쌍은 다음과 같습니다:
유형 | 역관계 | 자동 생성 |
|
| 예 |
|
| 예 |
지식 그래프에서 사용되는 일반적인 관례(강제되지 않음):
구조적: contiene / parte_de
생산: producido_por, contribuye_a
의존성: depende_de, usa
시간적: continua (레거시 매핑 → contribuye_a), sucedido_por
레거시 유형은 생성 시 _constants.py를 통해 정규화됩니다: continua → contribuye_a (컨텍스트 "세션 연속"), documentado_en → producido_por (컨텍스트 "문서화됨").
server.py (97 lines) — FastMCP init + tool registration
├── tools/
│ ├── core.py — 6 CRUD tools (Anthropic-compatible)
│ ├── search.py — 3 search tools + ranking helpers
│ ├── entity_mgmt.py — 6 entity management tools
│ ├── reflections.py — 2 reflection tools
│ └── relations.py — 2 tools (migrate, end_relation)
├── storage/ — 7 mixins + constants via multiple inheritance
│ ├── __init__.py — MemoryStore facade (134 lines)
│ ├── schema.py — SchemaMixin (migrations)
│ ├── core.py — CoreMixin (entity/obs CRUD)
│ ├── relations.py — RelationsMixin
│ ├── search.py — SearchMixin (FTS + embeddings)
│ ├── access.py — AccessMixin
│ ├── reflections.py — ReflectionsMixin
│ ├── consolidation.py — ConsolidationMixin
│ └── _constants.py — Inverse relation & validation constants
├── embeddings.py — EmbeddingEngine (ONNX, lazy load, auto-download)
├── scoring.py — Limbic Scoring + RRF
├── entity_splitter.py — Semantic clustering (Agglomerative + c-TF-IDF fallback)
├── retry.py — retry_on_locked (concurrency)
└── config.py — Input limits + A/B config저장소: WAL 저널링, 5초 바쁜 타임아웃, CASCADE 삭제가 포함된 SQLite
임베딩: 시작 시 한 번 로드되는 싱글톤 ONNX 모델, L2 정규화 코사인 검색
Limbic Scoring: 중요도 신호, 시간적 감쇠, 동시 발생 패턴 및 RRF 점수를 사용하여 하이브리드(KNN + FTS5) 후보를 재순위 지정 -- API에 투명함
동시성: 19개 쓰기 메서드에 지수 백오프 + 지터가 포함된 retry_on_locked 데코레이터. 안전한 다중 클라이언트 접근 (동시 opencode 세션으로 테스트됨)
성찰: 서사 계층을 위한 병렬 FTS5(reflection_fts) 및 벡터(reflection_embeddings) 인덱스, 동일한 RRF 하이브리드 파이프라인을 통해 검색
각 엔티티는 Head+Tail+Diversity 선택 전략(예산: 480 토큰)을 사용하여 텍스트에서 생성된 임베딩 벡터를 가집니다:
"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."search_semantic을 호출하면 파이프라인이 병렬로 실행됩니다:
의미론적 (KNN) -- 쿼리가 인코딩되고 sqlite-vec을 통해 엔티티 벡터와 비교됩니다.
전체 텍스트 (FTS5) -- 이름, 유형 및 관찰 내용을 다루는 BM25 인덱스에 대해 쿼리가 검색됩니다.
병합 (RRF) -- 두 분기의 결과가 Reciprocal Rank Fusion(score(d) = Sum 1/(k + rank))을 사용하여 결합됩니다.
병합된 후보는 다음을 고려하는 Limbic Scoring 엔진에 의해 재순위 지정됩니다:
중요도(Salience) -- 자주 액세스되고 잘 연결된 엔티티가 더 높은 순위를 차지합니다.
시간적 감쇠 -- 최근 사용된 엔티티는 최신 상태를 유지하고, 사용되지 않은 엔티티는 희미해집니다.
동시 발생 -- 자주 함께 나타나는 엔티티는 서로를 강화합니다.
출력에는 limbic_score, scoring(중요도/시간적/동시 발생 분석), 그리고 FTS5가 결과를 기여할 때 선택적으로 rrf_score가 포함됩니다.
전체 기술 세부 정보는 DOCUMENTATION.md를 참조하세요 -- 점수 산정 공식, RRF 상수, 스키마 DDL 및 아키텍처 다이어그램이 포함되어 있습니다.
uv run pytest tests/ -v모든 도구, 임베딩, 점수 산정 및 엣지 케이스를 다루는 23개 테스트 파일에 걸쳐 402개의 테스트가 수행되었습니다. 회귀 오류 없음.
Python >= 3.12
uv (패키지 관리자)
패키지 | 목적 |
| MCP 서버 프레임워크 |
| 요청/응답 유효성 검사 |
| SQLite 내 벡터 유사성 검색 |
| ONNX 모델 추론 (CPU) |
| HuggingFace 빠른 토크나이저 |
| 벡터 연산 |
| 엔티티 분할을 위한 의미론적 클러스터링 |
| 모델 다운로드 |
MIT
Add observations to an existing entity.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| observations | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it's an 'add' operation to an 'existing entity', implying mutation but not specifying permissions, side effects (e.g., appending vs. replacing), or response behavior. It lacks details on rate limits, idempotency, or error handling, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action, but could be more structured (e.g., clarifying parameters). Overall, it's appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is minimally adequate. It covers the basic purpose but lacks parameter details, usage context, and behavioral traits. The output schema mitigates some gaps, but overall completeness is limited for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'observations' and 'entity' but doesn't explain parameters: 'name' (likely entity identifier) and 'observations' (array of strings). No details on format, constraints, or examples are given, failing to add meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add observations to an existing entity' clearly states the action (add) and target (observations to entity), but it's vague about what 'observations' are (e.g., notes, data points) and doesn't distinguish from siblings like 'delete_observations' or 'create_entities'. It avoids tautology but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., entity must exist), exclusions, or compare to siblings like 'create_entities' (for new entities) or 'delete_observations'. Usage is implied only by the action 'add' to 'existing entity'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update entities in the knowledge graph. If an entity already exists, merge observations (don't overwrite). Returns the created/updated entities.
| Name | Required | Description | Default |
|---|---|---|---|
| entities | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by explaining the merge behavior ('merge observations, don't overwrite') and the return action ('Returns the created/updated entities'), which are crucial for understanding the tool's effect. However, it lacks details on permissions, rate limits, error handling, or side effects, which are important for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured, consisting of three sentences that each serve a clear purpose: stating the action, explaining the merge behavior, and describing the return. There is no wasted text, and key information is front-loaded, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a mutation operation with no annotations, the description does a decent job by covering the core action, merge behavior, and return. The presence of an output schema reduces the need to detail return values, but additional context on error cases or usage scenarios would enhance completeness. It's adequate but could be more robust for a tool with potential side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It mentions 'entities' as the parameter but doesn't explain the structure or required fields beyond 'merge observations.' This adds minimal semantic context, as the schema only indicates an array of objects. The description partially helps but doesn't fully clarify what constitutes a valid entity or how merging works in practice.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create or update entities in the knowledge graph.' It specifies the verb ('Create or update'), resource ('entities'), and location ('knowledge graph'), which is specific and actionable. However, it doesn't explicitly differentiate from sibling tools like 'add_observations' or 'create_relations,' which handle related but distinct operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the phrase 'If an entity already exists, merge observations (don't overwrite),' suggesting this tool is for upsert operations rather than pure creation. However, it doesn't provide explicit guidance on when to use this versus alternatives like 'add_observations' (for adding data to existing entities) or 'delete_entities' (for removal), nor does it mention prerequisites or exclusions, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create relations between entities. Both entities must exist. Returns created relations or errors for missing entities.
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that it 'Returns created relations or errors for missing entities', which adds some context about outcomes and error conditions. However, it lacks details on permissions, rate limits, or other behavioral traits like whether the operation is idempotent or reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that are front-loaded and waste no words. Every sentence adds value: the first states the action and prerequisite, the second explains the return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a creation tool with 1 parameter but 0% schema coverage) and the presence of an output schema (which handles return values), the description is minimally adequate. It covers the basic purpose and outcome but lacks details on parameters and behavioral context, making it incomplete for safe and effective use without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It doesn't explain the 'relations' parameter beyond implying it's an array of relations to create. No details are provided on what properties the relation objects should have, their structure, or validation rules, leaving significant gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create relations') and the resource ('between entities'), making the purpose understandable. It distinguishes from siblings like 'delete_relations' by specifying creation, but doesn't explicitly differentiate from other tools like 'create_entities' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating 'Both entities must exist', suggesting a prerequisite for using this tool. However, it doesn't provide explicit guidance on when to use this versus alternatives like 'create_entities' or 'delete_relations', leaving the context somewhat vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete entities and all their relations/observations.
| Name | Required | Description | Default |
|---|---|---|---|
| entityNames | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that deletion includes 'all their relations/observations', which adds useful context about cascading effects. However, it lacks details on permissions, irreversibility, rate limits, or response behavior, leaving significant gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—it directly states the action and scope without fluff. It's appropriately sized and front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, no annotations, and 0% schema coverage, the description is incomplete—it misses critical details like safety warnings or output expectations. However, the presence of an output schema mitigates some need to explain return values, keeping it from a lower score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'entityNames' implicitly but provides no semantics—no explanation of what entities are, format requirements, or constraints. This fails to add meaningful value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the target ('entities and all their relations/observations'), making the purpose specific. However, it doesn't explicitly differentiate from sibling tools like 'delete_observations' or 'delete_relations', which handle partial deletions, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'delete_observations' or 'delete_relations', nor does it mention prerequisites or context. It implies a broad deletion scope but lacks explicit usage rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete specific observations from an entity.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| observations | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Delete' which implies a destructive mutation, but doesn't disclose critical behavioral traits: whether deletion is permanent/reversible, authentication needs, rate limits, error conditions, or what happens to the entity after observations are removed. This is inadequate for a destructive tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and target, making it easy to parse quickly. Every word earns its place by conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a destructive tool with 2 parameters, 0% schema coverage, no annotations, but an output schema exists, the description is incomplete. It doesn't explain the mutation's impact, parameter usage, or relationship to siblings. The output schema might cover return values, but the description fails to provide necessary context for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'observations' and 'entity' but doesn't explain the 'name' and 'observations' parameters beyond what's implied. No details on parameter formats, constraints, or examples are provided. The description adds minimal semantic value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete specific observations from an entity' clearly states the action (delete) and target (observations from an entity), but it's somewhat vague about what 'observations' and 'entity' mean in this context. It distinguishes from siblings like 'delete_entities' by focusing on observations rather than entire entities, but lacks specificity about the domain or system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing entity), exclusions, or compare to siblings like 'add_observations' for when deletion is appropriate versus addition. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete relations between entities.
| Name | Required | Description | Default |
|---|---|---|---|
| relations | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Delete' implies a destructive mutation, but the description doesn't specify permissions required, whether deletions are permanent/reversible, rate limits, or what happens to related data. It mentions nothing about the output format despite having an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just four words, with no wasted language. However, this brevity comes at the cost of completeness - it's arguably too terse for a destructive operation with undocumented parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with zero annotation coverage, 0% schema description coverage, and one completely undocumented parameter, the description is inadequate. While an output schema exists (reducing need to describe returns), the description fails to address critical behavioral aspects like safety, permissions, or parameter requirements that would help an agent use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the single parameter 'relations' is completely undocumented in the schema. The description adds no information about what 'relations' should contain, its structure, or examples. For a parameter with zero schema documentation, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete relations between entities' clearly states the action (delete) and target (relations between entities), avoiding tautology. However, it lacks specificity about what 'relations' and 'entities' mean in this context, and doesn't distinguish this tool from sibling tools like 'delete_entities' or 'delete_observations'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are multiple sibling deletion tools (delete_entities, delete_observations) with no indication of when this specific relation-deletion tool is appropriate. No prerequisites, constraints, or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Migrate data from Anthropic MCP Memory JSONL format to SQLite. This is idempotent — running it multiple times won't duplicate data.
| Name | Required | Description | Default |
|---|---|---|---|
| source_path | No | /home/cachorro/.config/opencode/mcp-memory.jsonl |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it discloses idempotency ('running it multiple times won't duplicate data'), which is crucial for understanding safe repeated use. However, it does not mention potential side effects like data overwriting, error handling, or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste: the first states the purpose clearly, and the second adds critical behavioral information (idempotency). It is appropriately sized and front-loaded, with every sentence earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (data migration with 1 parameter) and the presence of an output schema (which handles return values), the description is mostly complete. It covers purpose and idempotency, but lacks details on error conditions, prerequisites, or output implications, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 1 parameter with 0% description coverage, so the description must compensate. It implies the parameter's purpose by mentioning 'source_path' in context ('Anthropic MCP Memory JSONL format'), but does not explicitly explain the parameter's role or format requirements. The description adds some meaning beyond the bare schema, though not fully detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Migrate data') with precise source and target formats ('from Anthropic MCP Memory JSONL format to SQLite'), distinguishing it from sibling tools that handle CRUD operations on entities, relations, and observations rather than format conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for data migration between specific formats, but does not explicitly state when to use this tool versus alternatives (e.g., for initial setup vs. ongoing updates) or mention prerequisites like file existence. It provides some context but lacks explicit guidance on alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open specific nodes by name. Returns full entity data with observations.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions that the tool 'Returns full entity data with observations', which is useful, but doesn't cover critical aspects like whether this is a read-only operation, if it requires specific permissions, error handling, or performance characteristics. The description is too sparse for a tool that presumably accesses node data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just two sentences, with no wasted words. However, this brevity comes at the cost of completeness - it's arguably too terse given the tool's likely complexity and lack of annotations/schema documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which should document return values), the description doesn't need to explain return format details. However, with no annotations, 0% schema description coverage, and multiple sibling tools with similar purposes, the description should provide more context about when and how to use this specific tool versus alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, so the schema provides no semantic information. The description only vaguely references 'by name' without explaining what 'names' represents (e.g., node IDs, labels, or something else), acceptable formats, or constraints. This leaves the parameter meaning ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Open specific nodes by name') and resource ('nodes'), making the purpose understandable. However, it doesn't distinguish this tool from sibling tools like 'search_nodes' or 'read_graph', which appear to have overlapping functionality with nodes/entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_nodes' or 'read_graph'. It doesn't mention prerequisites, constraints, or typical use cases, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the entire knowledge graph. Returns all entities with observations and all relations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the return content but lacks details on behavioral traits such as potential performance impact, rate limits, authentication requirements, or whether this operation is safe for large graphs. The description is minimal and doesn't compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action ('Read the entire knowledge graph') and specifies the return value. There is no wasted language, making it highly concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, an output schema exists, and annotations are absent, the description is minimally complete. It states what the tool does and what it returns, but for a graph-reading operation, it lacks context on scalability, error handling, or comparison to siblings, leaving gaps in overall understanding despite the structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter details, and it correctly implies no parameters are required, aligning with the schema. Baseline is 4 for zero parameters, as the description doesn't contradict or add unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with the verb 'Read' and resource 'entire knowledge graph', specifying it returns 'all entities with observations and all relations'. However, it doesn't explicitly differentiate from sibling tools like 'search_nodes' or 'search_semantic', which might offer filtered or partial graph access.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like retrieving the full graph for analysis versus using search tools for specific queries, nor does it discuss prerequisites or performance considerations for reading the entire graph.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for nodes in the knowledge graph by name, type, or observation content.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the search functionality but doesn't cover important traits like whether it's read-only (implied but not explicit), pagination, rate limits, authentication needs, or what happens on no matches. For a search tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and includes all necessary search criteria without redundancy. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (search with one parameter), no annotations, and the presence of an output schema (which handles return values), the description is minimally adequate. It covers the basic purpose and search fields but lacks usage guidelines and behavioral details that would make it more complete for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, so the schema provides no semantic context. The description adds value by implying the 'query' parameter can search by 'name, type, or observation content', giving some meaning beyond the bare schema. However, it doesn't detail query syntax, format, or examples, leaving room for improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for nodes') and the target resource ('knowledge graph'), with specific search criteria ('by name, type, or observation content'). It distinguishes from some siblings like 'create_entities' or 'delete_observations' by being a search operation, but doesn't explicitly differentiate from 'search_semantic' or 'open_nodes' which might also involve node retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_semantic' or 'open_nodes'. It mentions search criteria but doesn't specify scenarios, prerequisites, or exclusions. Without this context, an agent might struggle to choose between similar search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search using vector embeddings. Finds entities most similar to the query. Requires the embedding model to be downloaded (run download_model.py first).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the prerequisite model download requirement, which is useful behavioral context. However, it doesn't mention performance characteristics, rate limits, error conditions, or what 'entities' refers to specifically, leaving gaps for a search operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences with zero waste. The first sentence states the purpose, and the second provides critical prerequisite information. Every word earns its place, and it's front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), no annotations, and low schema coverage, the description is moderately complete. It covers the core purpose and a key prerequisite but lacks details on parameters, error handling, and differentiation from siblings like 'search_nodes', which is needed for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions 'query' implicitly but doesn't explain what constitutes a valid query or the meaning of 'limit' (e.g., maximum results). It adds minimal semantic value beyond what's inferable from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'semantic search using vector embeddings' and 'finds entities most similar to the query', which specifies the verb (search/find) and resource (entities). However, it doesn't explicitly differentiate from sibling 'search_nodes', leaving some ambiguity about when to use one versus the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about prerequisites ('Requires the embedding model to be downloaded') and implies usage for similarity-based searches. It doesn't explicitly state when NOT to use it or name alternatives like 'search_nodes', but the semantic focus offers reasonable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_observationscreate_entitiescreate_relationsdelete_entitiesdelete_observationsdelete_relationsmigrateopen_nodesread_graphsearch_nodessearch_semanticScored across 11 tools
Each tool has a clearly distinct purpose with no significant overlap: entity/relation/observation operations are separated, search functions target different methods, and administrative tools like migrate are unique. The descriptions reinforce distinct boundaries, making misselection unlikely.
All tools follow a consistent verb_noun naming pattern (e.g., add_observations, create_entities, delete_relations), with no deviations in style or convention. This predictability aids agent understanding and tool selection.
With 11 tools, the set is well-scoped for a knowledge graph memory system, covering core operations (CRUD for entities, relations, observations), search capabilities, and administrative functions. Each tool earns its place without bloat.
The tool surface provides complete coverage for the knowledge graph domain: full CRUD for entities, relations, and observations; multiple search methods (by attribute, semantic); graph reading; and data migration. No obvious gaps exist for typical agent workflows.
Hosted persistent memory with semantic search, importance and TTL for AI agents.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Mem0-compatible persistent memory for AI agents: write facts once, recall them semantically.
Persistent AI memory with semantic search, conflict detection, and ticketing.
