AI 메모리를 위한 지능 계층.
AI 에이전트 메모리를 위한 점수 엔진 + 인과 그래프 + 수명 주기 관리자. MCP를 기본적으로 지원합니다.
Genesys는 AI 메모리를 위한 점수 엔진, 인과 그래프, 수명 주기 관리자입니다. 메모리는 곱셈 공식(관련성 × 연결성 × 재활성화)으로 점수가 매겨지고, 인과 그래프로 연결되며, 관련성이 없어지면 능동적으로 삭제됩니다. 모든 스토리지 백엔드에 연결할 수 있으며 MCP를 기본적으로 지원합니다.
Related MCP server: Logica Mind
평면적 메모리는 확장되지 않습니다. 모든 것을 벡터 저장소에 덤프하면 이해 없이 회상만 가능합니다. 500번째 메모리가 중요한 5개를 묻어버립니다.
망각이 없으면 지능도 없습니다. 실제 메모리 시스템은 망각합니다. 능동적인 정리 없이는 AI가 오래된 컨텍스트에 잠기게 됩니다.
인과적 추론이 없습니다. 벡터 유사성은 "왜 X를 선택했는가?"라는 질문에 답할 수 없습니다. 그래프가 필요합니다.
당신의 AI는 모든 것을 기억하지만 아무것도 이해하지 못합니다. Genesys가 이를 해결합니다.
대부분의 사용자는 옵션 1(인메모리)로 시작하는 것이 좋습니다. API 키 없이 완전히 로컬에서 사용하려면 옵션 3: Obsidian + 로컬로 이동하세요.
Genesys를 가장 빠르게 체험하는 방법입니다. 데이터베이스가 필요 없으며, 상태는 메모리에 유지되고 선택적으로 JSON 파일에 저장됩니다.
pip install genesys-memory
cp .env.example .env
# Set OPENAI_API_KEY in .env
uvicorn genesys.api:app --port 8000재시작 후에도 유지하려면 .env에 GENESYS_PERSIST_PATH를 설정하세요:
GENESYS_PERSIST_PATH=.genesys_state.jsonClaude에게 설정을 요청하세요: *"genesys-memory를 설치하고, OpenAI 키가 포함된 .env 파일을 생성하고, 인메모리 백엔드로 8000번 포트에서 서버를 시작한 뒤, MCP 서버로 연결해줘."
pgvector를 통한 벡터 검색으로 지속적이고 확장 가능한 스토리지를 제공합니다.
pip install 'genesys-memory[postgres]'
cp .env.example .env.env 편집:
OPENAI_API_KEY=sk-...
GENESYS_BACKEND=postgres
DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesysPostgres 시작 및 마이그레이션 실행:
docker compose up -d postgres
alembic upgrade head
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000Claude에게 설정을 요청하세요: *"genesys-memory[postgres]를 설치하고, docker compose를 사용하여 pgvector가 포함된 Postgres 컨테이너를 시작하고, alembic 마이그레이션을 실행하고, OpenAI 키와 DATABASE_URL이 포함된 .env 파일을 생성하고, GENESYS_BACKEND=postgres로 서버를 시작한 뒤, MCP 서버로 연결해줘."
Obsidian 볼트를 Genesys 메모리 저장소로 변환합니다. 마크다운 파일은 메모리 노드가 되고, [[wikilinks]]는 인과적 에지가 됩니다. SQLite 사이드카(.genesys/index.db)가 인덱싱을 처리합니다.
pip install 'genesys-memory[obsidian]'
cp .env.example .env.env 편집:
OPENAI_API_KEY=sk-...
GENESYS_BACKEND=obsidian
OBSIDIAN_VAULT_PATH=/path/to/your/vault서버 시작:
uvicorn genesys.api:app --port 8000처음 시작할 때 Genesys는 볼트 내의 모든 .md 파일을 인덱싱하고 임베딩을 생성합니다. 파일 감시자가 노트를 편집할 때마다 점진적으로 다시 인덱싱합니다.
OBSIDIAN_VAULT_PATH가 설정되지 않은 경우, Genesys는~/Documents/personal,~/Documents/Obsidian,~/obsidian에서.obsidian/을 찾아 자동으로 감지합니다.
로컬 임베딩 제공자를 사용하여 외부 의존성 없이 Obsidian 모드를 실행하세요:
pip install 'genesys-memory[obsidian,local]'GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# No OPENAI_API_KEY neededuvicorn genesys.api:app --port 8000이 방식은 임베딩을 위해 sentence-transformers를 통해 all-MiniLM-L6-v2(384차원)를 사용합니다. 모델은 처음 사용할 때 다운로드됩니다(~80MB).
Claude Desktop 연결 — claude_desktop_config.json에 추가:
{
"mcpServers": {
"genesys": {
"url": "http://localhost:8000/mcp"
}
}
}또는 Claude Code의 경우:
claude mcp add --transport http genesys http://localhost:8000/mcpClaude에게 설정을 요청하세요: *"genesys-memory[obsidian,local]을 설치하고, GENESYS_BACKEND=obsidian, GENESYS_EMBEDDER=local, OBSIDIAN_VAULT_PATH=[YOUR_VAULT_PATH]로 설정된 .env 파일을 생성하고, 8000번 포트에서 서버를 시작한 뒤, MCP 서버로 연결해줘. API 키는 필요 없어."
네이티브 그래프 탐색을 위해 FalkorDB(Redis 기반 그래프 데이터베이스)를 사용합니다.
pip install 'genesys-memory[falkordb]'
cp .env.example .env.env 편집:
OPENAI_API_KEY=sk-...
GENESYS_BACKEND=falkordb
FALKORDB_HOST=localhostFalkorDB 및 서버 시작:
docker compose up -d falkordb
uvicorn genesys.api:app --port 8000Claude에게 설정을 요청하세요: *"genesys-memory[falkordb]를 설치하고, docker compose를 사용하여 FalkorDB 컨테이너를 시작하고, OpenAI 키와 GENESYS_BACKEND=falkordb가 포함된 .env 파일을 생성하고, 8000번 포트에서 서버를 시작한 뒤, MCP 서버로 연결해줘."
git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'두 개의 유틸리티 스크립트가 REST API를 통해 실행 중인 Genesys 인스턴스에 데모 데이터를 채웁니다. Clerk 인증이 구성된 실행 중인 서버가 필요합니다.
cp .env.example .env
# Set CLERK_SECRET_KEY and CLERK_USER_ID in .env
python seed_demo.py # Creates 25 memories with causal edges and runs recall queries
python seed_recalls.py # Runs 5 rounds of recall queries to build reactivation history두 스크립트 모두 환경 변수(.env를 통해)에서 자격 증명을 읽습니다. 필요한 모든 변수는 .env.example을 참조하세요.
claude mcp add --transport http genesys http://localhost:8000/mcpclaude_desktop_config.json에 추가:
{
"mcpServers": {
"genesys": {
"url": "http://localhost:8000/mcp"
}
}
}클라이언트를 MCP 엔드포인트로 지정하세요:
http://localhost:8000/mcp도구 | 설명 |
| 새 메모리를 저장하고 선택적으로 관련 메모리에 연결 |
| 자연어 쿼리로 메모리 회상 (벡터 + 그래프) |
| 필터(상태, 날짜 범위, 키워드)를 사용하여 메모리 검색 |
| 주어진 메모리 노드에서 인과 그래프 탐색 |
| 메모리가 존재하는 이유와 인과 관계 설명 |
| 메모리 시스템 통계 가져오기 |
| 메모리를 고정하여 삭제되지 않도록 설정 |
| 이전에 고정한 메모리 고정 해제 |
| 메모리 영구 삭제 |
| 핵심 메모리 목록 나열 (카테고리별 필터링 가능) |
| 핵심 메모리 카테고리에 대한 사용자 환경 설정 |
모든 메모리는 세 가지 힘을 곱한 값으로 점수가 매겨집니다:
decay_score = relevance × connectivity × reactivation**관련성(Relevance)**은 시간이 지남에 따라 감소합니다. 오래된 메모리는 강화되지 않으면 사라집니다.
**연결성(Connectivity)**은 많은 인과적 링크를 가진 메모리에 보상을 줍니다. 허브 메모리는 살아남습니다.
**재활성화(Reactivation)**는 계속해서 회상되는 메모리를 강화합니다. 빈도가 중요합니다.
공식이 곱셈 방식이므로, 메모리가 살아남으려면 세 가지 축 모두에서 점수를 얻어야 합니다. 연결성은 높지만 접근하지 않는 메모리는 여전히 감쇠합니다. 자주 회상되지만 인과적으로 고립된 메모리도 여전히 사라집니다.
STORE → ACTIVE → DORMANT → FADING → PRUNED
↑ │
└── reactivation ────┘
(only if score=0, orphan, not pinned)메모리는 핵심(core) 상태로 승격될 수 있습니다. 이는 구조적으로 중요한 메모리로, 자동으로 고정되며 절대 삭제되지 않습니다.
LoCoMo 장기 대화 메모리 벤치마크에서 테스트됨 (10개 대화에 걸친 1,540개의 질문, 카테고리 5 제외 — 정답에 사실 오류가 포함된 적대적 질문, 예: 잘못된 날짜 및 이벤트 귀속):
카테고리 | J-Score |
단일 홉 | 94.3% |
시간적 | 87.5% |
다중 홉 | 69.8% |
오픈 도메인 | 91.7% |
전체 | 89.9% |
답변 모델: gpt-4o-mini | 판정 모델: gpt-4o-mini | 검색 k=20
참고로, 동일한 벤치마크에서 Mem0은 67.1%, Zep은 75.1%를 기록했습니다. 전체 재현 스크립트는 benchmarks/에 있습니다.
백엔드 | 설치 | 사용 사례 |
| 내장 | 의존성 없음, 체험용 |
|
| 지속적, 확장 가능 |
Obsidian vault |
| 로컬 우선 지식 베이스 |
FalkorDB |
| 그래프 네이티브 탐색 |
Custom | 직접 구현 |
|
.env.example을 .env로 복사하고 설정하세요:
변수 | 필수 | 설명 |
|
| 임베딩 |
| 아니오 | LLM 메모리 처리 (통합, 모순 탐지) |
| 아니오 |
|
| 아니오 |
|
| postgres 사용 시 | Postgres 연결 문자열 |
| obsidian 사용 시 | Obsidian 볼트 경로 |
| falkordb 사용 시 | FalkorDB 호스트 (기본값: |
| 아니오 | 단일 테넌트 모드를 위한 기본 사용자 ID |
모든 옵션은 .env.example을 참조하세요.
Genesys는 Astrix Labs의 Rishi Meka가 제작했습니다. 매 세션마다 Claude에게 프로젝트 컨텍스트를 다시 설명해야 하는 좌절감에서 시작되었습니다. 목표는 LLM과 메모리 사이의 지능 계층을 만드는 것이며, 완전히 오픈 소스입니다.
CONTRIBUTING.md를 참조하세요.
참고: v0.3.6 이전의 Genesys 릴리스는 실수로 Apache 2.0으로 문서화되었습니다. LICENSE 파일에는 항상 AGPLv3 텍스트가 포함되어 있었습니다. v0.3.6부터 모든 문서는 기여자 라이선스 계약(CLA)과 함께 AGPL-3.0-or-later를 올바르게 참조합니다.
Permanently delete a memory node and all its edges.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It reveals permanence and that edges are removed, but does not mention authentication or rate limits. For a simple delete operation, this is adequate.
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, focused sentence that directly states the action and scope. There is no unnecessary detail or repetition.
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 operation, the description conveys the essential information: what is deleted (node and edges) and that it is permanent. No output schema is needed for such a simple action, and the description is complete enough for an agent to invoke it 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 coverage is 0% and the description does not elaborate on node_id. Although the parameter name is self-explanatory, the description could have added more context (e.g., format or example) to compensate for the lack of schema documentation.
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 (permanently delete) and the resource (memory node and all its edges). It is specific and distinguishes itself from sibling tools like memory_store or memory_amend.
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 explains what the tool does but does not explicitly contrast with alternatives (e.g., when to delete vs. amend). However, the action is unambiguous and the sibling context implies usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all core memories, optionally filtered by category.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'List' unambiguously indicates a read-only operation with no side effects, providing full behavioral transparency.
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 concise sentence with no redundant information or extra clutter.
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?
The description provides sufficient context for an agent to decide to use it: it lists all core memories with an optional category filter, which is complete for a listing operation.
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 'category' parameter is described as an optional filter, giving it clear meaning beyond the bare schema type. It does not enumerate possible values, but the purpose is well understood.
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 (list) and the resource (core memories) with an optional filter, distinguishing it from other memory operations such as search or recall.
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 explicit comparison is made with sibling tools like memory_search or memory_recall, so an agent may not know when to prefer listing over searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a correction: creates a new memory that supersedes an existing one. The old memory is kept (decayed in recall results), not deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| content | Yes | ||
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the old memory is kept but decayed in recall results, which is a behavioral detail beyond the basic schema. It does not mention error cases or effects on nodes, but the core behavior is transparent.
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 one concise sentence that packs the purpose and key behavior without unnecessary words.
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 simple tool, the description covers the primary purpose and effect, and the parameter names plus context allow an agent to infer usage. Missing explicit parameter meanings are a minor gap.
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 no parameter descriptions, but the description implies node_id identifies the existing memory. The fields 'reason' and 'content' are self-explanatory in context, but the tool description does not explicitly explain each parameter's role.
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 records a correction and creates a new memory that supersedes an existing one, distinguishing it from the sibling memory_store tool which likely creates new memories without superseding.
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?
It implies usage for correcting existing memories by saying 'supersedes an existing one', but does not explicitly contrast with memory_store or other siblings. However, the intent is fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain a memory's score breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations (e.g., readOnlyHint, destructiveHint) are provided, and the description does not mention side effects, permissions, or return behavior. It is unclear whether this tool only reads data or modifies anything.
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, concise sentence with no redundant words. It directly states the tool's purpose without unnecessary detail.
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 simple tool this description is minimally adequate, but it lacks context about the output format or any additional behavior. The missing parameter details and return expectations reduce completeness.
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 single parameter node_id has no schema description and is not elaborated in the tool description. This leaves ambiguity about what node_id refers to and how it should be supplied.
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 (explain) and the resource (a memory's score breakdown), distinguishing it from sibling tools like memory_store or memory_search. It is specific enough to understand the purpose.
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 explicit guidance is given on when to use this tool versus alternatives. The description implies use when wanting to understand a memory's score, but does not state conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recall memories using hybrid search (vector + keyword + graph spreading activation).
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| query | Yes | ||
| verbosity | No | concise = id/summary/status/score/activation/is_core only, no causal chains. | full |
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior, but it only mentions the hybrid search approach. It does not disclose return format, side effects, or how results are sorted/ranked.
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 concise sentence that conveys core functionality without unnecessary words or repetition.
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 of the tool (hybrid search with multiple parameters) and the existence of closely related sibling tools, the description lacks detail about expected output, use cases, or how it differs from alternatives. It feels incomplete for an agent to choose confidently.
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 coverage is 25% (only 'verbosity' has a description). The description does not clarify the meaning or effect of 'query', 'k', or 'max_results' beyond what the schema implies.
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 recalls memories using hybrid search, specifying the resource (memories) and the method (vector + keyword + graph spreading activation). It is distinguishable from siblings like memory_search, though not explicitly contrasted.
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 such as memory_search or memory_traverse. No criteria or context for selection is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filtered vector search by status, category, date, or entity. Pass an EMPTY query to enumerate by recency instead (no vector search, no embedder needed): with since/active_since this answers 'what's new/changed since ' without knowing what to query for.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| query | Yes | Search text. Empty string switches to enumeration mode: nodes listed by last_reactivated_at descending, honoring the same filters. | |
| filters | No | Supported keys: status (list), category, entity, since (ISO date — created_at >= since; tz-naive treated as UTC), active_since (ISO date — last_reactivated_at >= active_since; tz-naive treated as UTC). With a non-empty query, results are vector-seeded and k-limited; use an empty query for enumeration. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not mention whether the operation is read-only, whether it has side effects, or any auth or rate-limit considerations. Since it is a search tool, it likely does not modify data, but the description does not confirm this, leaving behavior partly unclear.
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 concise and mixes the core purpose with the special enumeration mode efficiently. The punctuation and parenthetical asides are slightly complex, but the overall structure is clear and not verbose.
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?
The description covers the main usage modes and filter details, but it does not mention what the return values look like (no output schema) or how the `k` parameter affects the result set. For a search tool, this leaves some context about expected output incomplete.
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 `filters` parameter receives a detailed explanation covering its keys and semantics, and the `query` parameter's empty-string behavior is well described. However, the `k` parameter is only given a type and default without any explanation of its meaning (e.g., maximum number of results), so parameter semantics are only partially covered.
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 core function as a filtered vector search by status, category, date, or entity, and explicitly introduces the enumeration mode with an empty query. This makes the purpose immediately understandable and distinguishable from typical search tools.
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 practical guidance on when to use the empty-query enumeration mode, especially for answering 'what's new/changed since <ts>' without needing a query. It does not explicitly compare with sibling tools, but the use cases are well enough defined for the primary scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get graph statistics.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations provided, so the description carries the full burden. It implies a read-only operation via 'Get', but does not explicitly state that it is non-destructive, what data it returns, or any side effects or permissions. The behavior is only minimally transparent.
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, concise sentence that directly states the purpose. It adheres to the principle of brevity and clarity, with no extraneous words or structure.
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 lack of an output schema, the description is incomplete in explaining what the agent should expect from the tool. It does not say what kind of statistics are returned (e.g., counts, sizes, metadata) or how they might be used. An agent would need additional context to correctly interpret the result.
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 tool has zero parameters, so the schema coverage is 100%. Per the baseline, a score of 3 is given when the schema fully documents all parameters. The description does not add any additional meaning about parameters, but none are needed.
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 states a clear action 'Get' and an object 'graph statistics', but the object is vague. It does not specify what kind of statistics, which graph, or how they are presented. It is better than a tautology but lacks specificity to fully distinguish from similar tools like memory_explain or memory_recall.
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 its siblings. It does not mention any conditions, prerequisites, or alternatives. An agent would have to infer from the name alone that it is for retrieving statistics, with no clear differentiation from other memory tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new memory in the causal memory graph. Use related for writer-specified typed edges (each {id, type}); related_to is legacy and always creates caused_by edges. May return possible_conflicts — heuristic hints, not verified contradictions.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | No | Required when visibility is 'org'. Must be an org the caller belongs to. | |
| content | Yes | ||
| related | No | Typed explicit edges. Direction: new_node --type--> target. | |
| category | No | Free-form classification (suggested: professional, educational, family, location). | |
| related_to | No | Legacy: ids of nodes to link via caused_by. Prefer `related`. | |
| visibility | No | private | |
| source_session | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses the primary side effect (storing a new memory), the edge-creation behavior, legacy behavior of 'related_to', and notes that 'possible_conflicts' may be returned as heuristic hints. It does not mention authentication or permission side effects, but the core behaviors are transparent.
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 concise, using only two sentences to cover purpose, edge semantics, legacy behavior, and return hints. There is no redundancy or unnecessary detail.
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?
The description covers the essential purpose, key parameter distinctions, legacy behavior, and return hints. It omits some details about fields like 'content' and 'visibility', but the overall context is sufficient for a typical agent to correctly invoke the 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?
The description adds value by explaining 'related' edges, the legacy nature of 'related_to', and the direction semantics. However, schema coverage is only 57%, and the description does not compensate for undocumented parameters like 'content', 'visibility', or 'source_session'. It partially clarifies parameters but not comprehensively.
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 primary action: storing a new memory in the causal memory graph. It distinguishes itself from sibling tools like memory_amend (existing memories), memory_recall, and memory_search by emphasizing 'new memory'.
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 gives clear context for using the tool, including guidance on preferring the 'related' parameter over the legacy 'related_to' and clarifying that 'related_to' always creates caused_by edges. It does not explicitly say 'use this instead of memory_amend for existing memories,' but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Traverse the memory graph from a starting node. Returns reachable nodes AND the edges of the induced subgraph among them (source/target/type/weight/created_by) — a superset of the BFS tree, so paths can be reconstructed.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| node_id | Yes | ||
| edge_types | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does add behavioral context: it states the return contains both reachable nodes and the edges of the induced subgraph, and explains it is a superset of the BFS tree. However, with no annotations present, it doesn't disclose whether traversal is read-only, whether there are cycle risks, or any side effects, so the full burden is not met.
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 uses two sentences with no wasted words. It front-loads the main action, then immediately explains the output's structure and why the superset property matters. Very effective.
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 tool with three parameters and no output schema or annotations, the description is incomplete. It leaves depth and edge_types undefined, and it doesn't explain what happens with empty reachability or missing node_id. This is not enough for a confident call.
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 coverage is 0%, so the description must compensate for node_id, depth, and edge_types. It only mentions a starting node, which maps to node_id; it doesn't explain what depth controls or how edge_types filters traversal. This is a clear gap.
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?
This sentence is a precise action: the verb 'Traverse' with resource 'memory graph' and the starting node. It also clarifies the output is a superset of the BFS tree, which sets it apart from sibling tools like memory_recall or memory_search.
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 does not say when to use this tool instead of alternatives, and it never names a sibling or a use case that would select this over memory_recall or memory_search. There is only an implicit purpose, no explicit when/when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pin a memory to core status.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations accompany the tool, the description carries the full responsibility of explaining behavior. It only says 'Pin a memory to core status' and does not specify what 'core status' implies, whether the operation is reversible, what side effects might occur, or any permission-related constraints. The description effectively relies on the tool name itself.
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, with a single sentence and no filler. However, this conciseness is achieved by omitting nearly all the information an agent would need; it earns its place as a short purpose statement but does not go beyond that, making the brevity a trade-off against completeness.
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?
With no annotations, no output schema, and a bare schema with a single undocumented parameter, the description leaves central concepts undefined. An agent cannot infer what 'core status' means, how the memory is located via 'node_id', or what the tool actually does beyond the name. The description is not complete enough to support 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?
The input schema has only one parameter, 'node_id', but its description coverage is 0%. The description does nothing to explain what 'node_id' represents, how to obtain it, or how it relates to the 'memory' being pinned. This is a critical gap because neither the schema nor the description supplies this required meaning.
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 names a clear verb ('Pin'), a specific resource ('a memory'), and the intended outcome ('core status'), and it also implicitly distinguishes the tool from its sibling 'unpin_memory' by describing the opposite action. An agent can confidently connect the tool to its core function without consulting other tools.
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 'pin_memory' versus related tools such as 'memory_store', 'memory_amend', or 'unpin_memory'. It does not mention prerequisites, use cases, or exclusion conditions, so the agent receives no direction about when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote a private memory to org visibility. Caller must own the node and belong to the target org.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | keep_private | |
| org_id | Yes | ||
| dry_run | No | ||
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The main behavior is disclosed (changing a memory from private to org visibility) and the required permissions are stated. However, key behavioral controls in the schema—especially the 'action' enum values and 'dry_run' flag—are unexplained, and no annotations exist to fill that gap.
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 brief sentences with no redundant words or filler. It front-loads the core purpose and then states the key precondition, making it easy to parse 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 lack of annotations and output schema, the description is not complete enough for reliable invocation. It omits the semantics of the 'action' enum, the behavior of 'dry_run', expected outcomes, and any edge cases or error conditions.
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?
With zero schema descriptions, the description must compensate. It implicitly covers node_id and org_id ('own the node', 'target org'), but it does not explain the meaning or effects of 'action' or 'dry_run'. Coverage is partial at best.
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 primary action: promoting a private memory to org visibility. It also names the resource ('private memory') and the target state ('org visibility'), and it is distinct from sibling tools like pin_memory or memory_store.
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 a precondition ('Caller must own the node and belong to the target org') but does not say when to use this tool versus alternatives like pin_memory or memory_store. No explicit usage guidance or comparison to sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure core memory category preferences.
| Name | Required | Description | Default |
|---|---|---|---|
| auto | No | ||
| approval | No | ||
| excluded | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and a generic 'configure' verb, the description does not disclose side effects, persistence, permissions, or whether changes are reversible. It is unclear if this tool modifies global settings or per-category rules.
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 concise sentence with no redundancy. However, it sacrifices clarity for brevity, leaving out essential details, so it does not fully earn 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 lack of parameter explanations and usage context, the description is incomplete for an agent to safely and effectively invoke the tool. It does not cover return values, errors, or interactions with sibling tools.
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 provides zero descriptions for parameters (auto, approval, excluded), and the description does not explain their meaning or expected values. The agent cannot determine what these array parameters control or how to populate them.
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 states a verb ('Configure') and a resource ('core memory category preferences'), but it is vague about what 'preferences' entails. It does not clarify whether it sets auto-approval, exclusions, or other specific behaviors, making it only partially clear.
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 siblings like memory_store or memory_amend. The description does not indicate scenarios where configuring preferences is appropriate, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unpin a memory and re-evaluate core eligibility.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations or output schema. The description mentions side effects vaguely ('re-evaluate core eligibility') but does not explain what happens to the memory or return value.
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?
Extremely concise and direct; no filler or redundant 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?
No output schema or return details, and the side effects of unpinning are under-specified, leaving the agent unsure about the outcome.
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 only parameter node_id has no description in the schema, and the tool description does not clarify its format or role beyond the obvious identifier meaning.
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?
Clear verb 'unpin' and object 'memory', with an explicit consequence (re-evaluate core eligibility). Distinct from sibling tools like pin_memory.
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 on when to use this tool versus alternatives such as pin_memory or delete_memory, nor any prerequisites.
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.0delete_memorylist_core_memoriesmemory_amendmemory_explainmemory_recallmemory_searchmemory_statsmemory_storememory_traversepin_memorypromote_to_orgset_core_preferencesunpin_memoryScored across 13 tools
Each tool targets a distinct operation: store, amend, recall, filtered search, graph traversal, explanation, pinning, unpinning, deletion, stats, preferences, and visibility promotion. memory_recall and memory_search are clearly differentiated as hybrid retrieval versus structured filtering/enumeration.
The memory_* prefix is used consistently for several core operations, but other tools switch to verb_memory forms (pin_memory, delete_memory), noun-like names (memory_stats), or unrelated forms (list_core_memories, set_core_preferences, promote_to_org). The naming is readable but not a uniform verb_noun pattern.
Thirteen tools is well within the ideal range for a memory graph server. Each tool covers a meaningful lifecycle or administrative function without unnecessary redundancy.
The tool set covers the full memory lifecycle: create, read via multiple retrieval modes, amend/supersede, pin/unpin, delete, and administrative operations like stats and preferences. Graph traversal and explanation tools add strong domain coverage with no obvious dead ends.
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Graph memory for AI agents: entities, cause-effect links, cross-session recall, time travel.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
