CortexGraph provides AI assistants with a human-like temporal memory system featuring automatic decay based on cognitive science principles, reinforcement through usage, and intelligent two-layer storage architecture.
Core Memory Operations
save_memory - Store new memories with tags, entities, source, context, and metadata
search_memory - Search short-term memory with filters for tags, time windows, and score thresholds
search_unified - Search across both short-term and long-term memory with weighted ranking
open_memories - Retrieve specific memories by ID with detailed information and relations
touch_memory - Reinforce memories by updating access time and boosting strength to slow decay
Memory Lifecycle Management
gc - Remove low-scoring memories that have decayed below the forget threshold (with dry-run preview)
promote_memory - Promote high-value memories to permanent long-term storage (Obsidian vault), with auto-detection of promotion candidates
Knowledge Graph & Relations
read_graph - Read the complete knowledge graph with all memories, relations, and statistics
create_relation - Create explicit typed relationships between memories (e.g., "references", "follows_from", "similar_to") with strength scores
Memory Optimization
cluster_memories - Group similar memories using semantic similarity or identify duplicates
consolidate_memories - Merge similar memories into unified entries (placeholder - not yet implemented)
Key Features: Temporal decay following the Ebbinghaus forgetting curve, reinforcement learning through natural usage patterns, automatic promotion from short-term (JSONL) to long-term storage (Markdown), smart scoring combining recency, frequency, and importance, and automatic entity extraction from natural language content.
Enables version control and backup operations for memory storage, providing Git integration for tracking changes to memory data and creating backups
Provides integration with Obsidian vaults for long-term memory storage, allowing AI to automatically promote important memories to permanent Markdown files with YAML frontmatter and wikilinks
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mnemex what did I tell you about my programming preferences last week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server providing human-like memory dynamics for AI assistants. Memories naturally fade over time unless reinforced through use, mimicking the Ebbinghaus forgetting curve.
About the Name & Version
This project was originally developed as mnemex (published to PyPI up to v0.6.0). In November 2025, it was transferred to Prefrontal Systems and renamed to CortexGraph to better reflect its role within a broader cognitive architecture for AI systems.
Version numbering starts at 0.1.0 for the cortexgraph package to signal a fresh start under the new name, while acknowledging the mature, well-tested codebase (791 tests, 98%+ coverage) inherited from mnemex. The mnemex package remains frozen at v0.6.0 on PyPI.
This versioning approach:
Signals "new package" to PyPI users discovering cortexgraph
Gives room to evolve the brand, API, and organizational integration before 1.0
Maintains continuity: users can migrate from pip install mnemex → pip install cortexgraph
Reflects that while the code is mature, the cortexgraph identity is just beginning
🔬 RESEARCH ARTIFACT - NOT FOR PRODUCTION
This software is a Proof of Concept (PoC) and reference implementation for research purposes. It exists to validate theoretical frameworks in cognitive architecture and AI safety (specifically the STOPPER Protocol and CortexGraph).
It is NOT a commercial product. It is not maintained for general production use, may contain breaking changes, and offers no guarantees of stability or support. Use it to study the concepts, but build your own production implementations.
📖 New to this project? Start with the ELI5 Guide for a simple explanation of what this does and how to use it.
CortexGraph gives AI assistants like Claude a human-like memory system.
When you chat with Claude, it forgets everything between conversations. You tell it "I prefer TypeScript" or "I'm allergic to peanuts," and three days later, you have to repeat yourself. This is frustrating and wastes time.
CortexGraph makes AI assistants remember things naturally, just like human memory:
🧠 Remembers what matters - Your preferences, decisions, and important facts
⏰ Forgets naturally - Old, unused information fades away over time (like the Ebbinghaus forgetting curve)
💪 Gets stronger with use - The more you reference something, the longer it's remembered
📦 Saves important things permanently - Frequently used memories get promoted to long-term storage
You talk naturally - "I prefer dark mode in all my apps"
Memory is saved automatically - No special commands needed
Time passes - Memory gradually fades if not used
You reference it again - "Make this app dark mode"
Memory gets stronger - Now it lasts even longer
Important memories promoted - Used 5+ times? Saved permanently to your Obsidian vault
No flashcards. No explicit review. Just natural conversation.
Most memory systems are dumb:
❌ "Delete after 7 days" (doesn't care if you used it 100 times)
❌ "Keep last 100 items" (throws away important stuff just because it's old)
CortexGraph is smart:
✅ Combines recency (when?), frequency (how often?), and importance (how critical?)
✅ Memories fade naturally like human memory
✅ Frequently used memories stick around longer
✅ You can mark critical things to "never forget"
Related MCP server: AI Long-Term Memory MCP Server
This repository contains research, design, and a complete implementation of a short-term memory system that combines:
Novel temporal decay algorithm based on cognitive science
Reinforcement learning through usage patterns
Two-layer architecture (STM + LTM) for working and permanent memory
Smart prompting patterns for natural LLM integration
Git-friendly storage with human-readable JSONL
Knowledge graph with entities and relations
CortexGraph follows a modular architecture:
cortexgraph.core: Foundational algorithms (decay, similarity, clustering, consolidation, search validation)
cortexgraph.agents: Multi-agent consolidation pipeline and storage utilities
cortexgraph.storage: JSONL and SQLite storage backends with batch operations
cortexgraph.tools: MCP tool implementations
All data stored locally on your machine - no cloud services, no tracking, no data sharing.
Short-term memory:
JSONL (default): Human-readable, git-friendly files (~/.config/cortexgraph/jsonl/)
SQLite: Robust database storage for larger datasets (~/.config/cortexgraph/cortexgraph.db)
Long-term memory: Markdown files optimized for Obsidian
YAML frontmatter with metadata
Wikilinks for connections
Permanent storage you control
Export: Built-in utility to export memories to Markdown for portability.
You own your data. You can read it, edit it, delete it, or version control it - all without any special tools.
The temporal decay scoring function:
$$ \Large \text{score}(t) = (n_{\text{use}})^\beta \cdot e^{-\lambda \cdot \Delta t} \cdot s $$
Where:
$\large n_{\text{use}}$ - Use count (number of accesses)
$\large \beta$ (beta) - Sub-linear use count weighting (default: 0.6)
$\large \lambda = \frac{\ln(2)}{t_{1/2}}$ (lambda) - Decay constant; set via half-life (default: 3-day)
$\large \Delta t$ - Time since last access (seconds)
$\large s$ - Strength parameter $\in [0, 2]$ (importance multiplier)
Thresholds:
$\large \tau_{\text{forget}}$ (default 0.05) — if score < this, forget
$\large \tau_{\text{promote}}$ (default 0.65) — if score ≥ this, promote (or if $\large n_{\text{use}}\ge5$ in 14 days)
Decay Models:
Power‑Law (default): heavier tail; most human‑like retention
Exponential: lighter tail; forgets sooner
Two‑Component: fast early forgetting + heavier tail
See detailed parameter reference, model selection, and worked examples in docs/scoring_algorithm.md.
Balanced (default)
Half-life: 3 days (λ ≈ 2.67e-6)
β = 0.6, τ_forget = 0.05, τ_promote = 0.65, use_count≥5 in 14d
Strength: 1.0 (bump to 1.3–2.0 for critical)
High‑velocity context (ephemeral notes, rapid switching)
Half-life: 12–24 hours (λ ≈ 1.60e-5 to 8.02e-6)
β = 0.8–0.9, τ_forget = 0.10–0.15, τ_promote = 0.70–0.75
Long retention (research/archival)
Half-life: 7–14 days (λ ≈ 1.15e-6 to 5.73e-7)
β = 0.3–0.5, τ_forget = 0.02–0.05, τ_promote = 0.50–0.60
Preference/decision heavy assistants
Half-life: 3–7 days; β = 0.6–0.8
Strength defaults: 1.3–1.5 for preferences; 1.8–2.0 for decisions
Aggressive space control
Raise τ_forget to 0.08–0.12 and/or shorten half-life; schedule weekly GC
Environment template
CORTEXGRAPH_DECAY_LAMBDA=2.673e-6, CORTEXGRAPH_DECAY_BETA=0.6
CORTEXGRAPH_FORGET_THRESHOLD=0.05, CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
CORTEXGRAPH_PROMOTE_USE_COUNT=5, CORTEXGRAPH_PROMOTE_TIME_WINDOW=14
Decision thresholds:
Forget: $\text{score} < 0.05$ → delete memory
Promote: $\text{score} \geq 0.65$ OR $n_{\text{use}} \geq 5$ within 14 days → move to LTM
Unlike traditional caching (TTL, LRU), Mnemex scores memories continuously by combining recency (exponential decay), frequency (sub-linear use count), and importance (adjustable strength). See Core Algorithm for the mathematical formula. This creates memory dynamics that closely mimic human cognition.
Patterns for making AI assistants use memory naturally, now enhanced with automatic entity extraction and importance scoring:
Auto-Enrichment (NEW in v0.6.0)
When you save memories, CortexGraph automatically:
Extracts entities (people, technologies, organizations) using spaCy NER
Calculates importance/strength based on content markers
Detects save/recall intent from natural language phrases
# Before v0.6.0 - manual entity specification
save_memory(content="Use JWT for auth", entities=["JWT", "auth"])
# v0.6.0+ - automatic extraction
save_memory(content="Use JWT for auth")
# Entities auto-extracted: ["jwt", "auth"]
# Strength auto-calculated based on contentAuto-Save
User: "Remember: I prefer TypeScript over JavaScript"
→ Detected save phrase: "Remember"
→ Automatically saved with:
- Entities: [typescript, javascript]
- Strength: 1.5 (importance marker detected)
- Tags: [preferences, programming]Auto-Recall
User: "What did I say about TypeScript?"
→ Detected recall phrase: "what did I say about"
→ Automatically searches for TypeScript memories
→ Retrieves preferences and conventionsAuto-Reinforce
User: "Yes, still using TypeScript"
→ Memory strength increased, decay slowedDecision Support Tools (v0.6.0+)
Two new tools help Claude decide when to save/recall:
analyze_message - Detects memory-worthy content, suggests entities and strength
analyze_for_recall - Detects recall intent, suggests search queries
No explicit memory commands needed - just natural conversation.
Inspired by how concepts naturally reinforce across different contexts (the "Maslow effect" - remembering Maslow's hierarchy better when it appears in history, economics, and sociology classes).
No flashcards. No explicit review sessions. Just natural conversation.
How it works:
Review Priority Calculation - Memories in the "danger zone" (0.15-0.35 decay score) get highest priority
Cross-Domain Detection - Detects when memories are used in different contexts (tag Jaccard similarity <30%)
Automatic Reinforcement - Memories strengthen naturally when used, especially across domains
Blended Search - Review candidates appear in 30% of search results (configurable)
Usage pattern:
User: "Can you help with authentication in my API?"
→ System searches, retrieves JWT preference memory
→ System uses memory to answer question
→ System calls observe_memory_usage with context tags [api, auth, backend]
→ Cross-domain usage detected (original tags: [security, jwt, preferences])
→ Memory automatically reinforced, strength boosted
→ Next search naturally surfaces memories needing reviewConfiguration:
CORTEXGRAPH_REVIEW_BLEND_RATIO=0.3 # 30% review candidates in search
CORTEXGRAPH_REVIEW_DANGER_ZONE_MIN=0.15 # Lower bound of danger zone
CORTEXGRAPH_REVIEW_DANGER_ZONE_MAX=0.35 # Upper bound of danger zone
CORTEXGRAPH_AUTO_REINFORCE=true # Auto-reinforce on observeSee docs/prompts/ for LLM system prompt templates that enable natural memory usage.
graph TD
STM["<b>Short-Term Memory</b><br/>- JSONL storage<br/>- Temporal decay<br/>- Hours to weeks retention"]
LTM["<b>LTM (Long-Term Memory)</b><br/>- Markdown files Obsidian<br/>- Permanent storage<br/>- Git version control"]
STM -->|Automatic promotion| LTM
style STM fill:#e1f5ff,stroke:#01579b,stroke-width:2px
style LTM fill:#f3e5f5,stroke:#4a148c,stroke-width:2pxAutomated memory maintenance through five specialized agents:
graph LR
decay["<b>DecayAnalyzer</b><br/>Find at-risk<br/>memories"]
cluster["<b>ClusterDetector</b><br/>Find similar<br/>groups"]
merge["<b>SemanticMerge</b><br/>Combine<br/>similar groups"]
promote["<b>LTMPromoter</b><br/>Promote<br/>to LTM"]
relations["<b>RelationshipDiscovery</b><br/>Discover cross-<br/>domain links"]
decay --> cluster
cluster --> merge
merge --> promote
promote --> relations
relations -.->|feedback| decay
style decay fill:#ffebee,stroke:#b71c1c,stroke-width:2px
style cluster fill:#fff3e0,stroke:#e65100,stroke-width:2px
style merge fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style promote fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style relations fill:#e1f5fe,stroke:#01579b,stroke-width:2pxThe Five Agents:
Agent | Purpose |
DecayAnalyzer | Find memories at risk of being forgotten (danger zone: 0.15-0.35) |
ClusterDetector | Group similar memories using embedding similarity |
SemanticMerge | Intelligently combine clustered memories, preserving unique info |
LTMPromoter | Move high-value memories to permanent Obsidian storage |
RelationshipDiscovery | Find cross-domain connections via shared entities |
Key Features:
Dry-run mode: Preview changes without modifying data
Rate limiting: Configurable operations per minute (default: 60)
Audit trail: Every decision tracked via beads issue tracking
Human override: Review and approve decisions before execution
Usage:
from cortexgraph.agents import Scheduler
# Preview what would change (dry run)
scheduler = Scheduler(dry_run=True)
preview = scheduler.run_pipeline()
# Run full pipeline
scheduler = Scheduler(dry_run=False)
results = scheduler.run_pipeline()
# Run single agent
decay_results = scheduler.run_agent("decay")CLI:
# Dry run (preview)
cortexgraph-consolidate --dry-run
# Run specific agent
cortexgraph-consolidate --agent decay --dry-run
# Scheduled execution (with interval)
cortexgraph-consolidate --scheduled --interval-hours 1See docs/agents.md for complete documentation including configuration, beads integration, and troubleshooting.
Recommended: UV Tool Install (from PyPI)
# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands)
uv tool install cortexgraphThis installs cortexgraph and all 7 CLI commands in an isolated environment.
Alternative Installation Methods
# Using pipx (similar isolation to uv)
pipx install cortexgraph
# Using pip (traditional, installs in current environment)
pip install cortexgraph
# From GitHub (latest development version)
uv tool install git+https://github.com/simplemindedbot/cortexgraph.gitFor Development (Editable Install)
# Clone and install in editable mode
git clone https://github.com/simplemindedbot/cortexgraph.git
cd cortexgraph
uv pip install -e ".[dev]"IMPORTANT: Configuration location depends on installation method:
Method 1: .env file (Works for all installation methods)
Create ~/.config/cortexgraph/.env:
# Create config directory
mkdir -p ~/.config/cortexgraph
# Option A: Copy from cloned repo
cp .env.example ~/.config/cortexgraph/.env
# Option B: Download directly
curl -o ~/.config/cortexgraph/.env https://raw.githubusercontent.com/simplemindedbot/cortexgraph/main/.env.exampleEdit ~/.config/cortexgraph/.env with your settings:
# Storage
CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl
# Decay model (power_law | exponential | two_component)
CORTEXGRAPH_DECAY_MODEL=power_law
# Power-law parameters (default model)
CORTEXGRAPH_PL_ALPHA=1.1
CORTEXGRAPH_PL_HALFLIFE_DAYS=3.0
# Exponential (if selected)
# CORTEXGRAPH_DECAY_LAMBDA=2.673e-6 # 3-day half-life
# Two-component (if selected)
# CORTEXGRAPH_TC_LAMBDA_FAST=1.603e-5 # ~12h
# CORTEXGRAPH_TC_LAMBDA_SLOW=1.147e-6 # ~7d
# CORTEXGRAPH_TC_WEIGHT_FAST=0.7
# Common parameters
CORTEXGRAPH_DECAY_LAMBDA=2.673e-6
CORTEXGRAPH_DECAY_BETA=0.6
# Thresholds
CORTEXGRAPH_FORGET_THRESHOLD=0.05
CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
# Long-term memory (optional)
LTM_VAULT_PATH=~/Documents/Obsidian/VaultWhere cortexgraph looks for .env files:
Primary: ~/.config/cortexgraph/.env ← Use this for uv tool install / uvx
Fallback: ./.env (current directory) ← Only works for editable installs
Recommended: Use absolute path (works everywhere)
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"cortexgraph": {
"command": "/Users/yourusername/.local/bin/cortexgraph"
}
}
}Find your actual path:
which cortexgraph
# Example output: /Users/yourusername/.local/bin/cortexgraphUse that path in your config. Replace yourusername with your actual username.
Why absolute path? GUI apps like Claude Desktop don't inherit your shell's PATH configuration (.zshrc, .bashrc). Using the full path ensures it always works.
For development (editable install):
{
"mcpServers": {
"cortexgraph": {
"command": "uv",
"args": ["--directory", "/path/to/cortexgraph", "run", "cortexgraph"],
"env": {"PYTHONPATH": "/path/to/cortexgraph/src"}
}
}
}Configuration can be loaded from ./.env in the project directory OR ~/.config/cortexgraph/.env.
If Claude Desktop shows spawn cortexgraph ENOENT errors, the cortexgraph command isn't in Claude Desktop's PATH.
macOS/Linux: GUI apps don't inherit shell PATH
GUI applications on macOS and Linux don't see your shell's PATH configuration (.zshrc, .bashrc, etc.). Claude Desktop only searches:
/usr/local/bin
/opt/homebrew/bin (macOS)
/usr/bin
/bin
/usr/sbin
/sbin
If uv tool install placed cortexgraph in ~/.local/bin/ or another custom location, Claude Desktop can't find it.
Solution: Use absolute path
# Find where cortexgraph is installed
which cortexgraph
# Example output: /Users/username/.local/bin/cortexgraphUpdate your Claude config with the absolute path:
{
"mcpServers": {
"cortexgraph": {
"command": "/Users/username/.local/bin/cortexgraph"
}
}
}Replace /Users/username/.local/bin/cortexgraph with your actual path from which cortexgraph.
Use the maintenance CLI to inspect and compact JSONL storage:
# Show storage stats (active counts, file sizes, compaction hints)
cortexgraph-maintenance stats
# Compact JSONL (rewrite without tombstones/duplicates)
cortexgraph-maintenance compactIf you're currently using an editable install (uv pip install -e .), you can switch to the simpler UV tool install:
# 1. Uninstall editable version
uv pip uninstall cortexgraph
# 2. Install as UV tool
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git
# 3. Update Claude Desktop config to just:
# {"command": "cortexgraph"}
# Remove the --directory, run, and PYTHONPATH settingsYour data is safe! This only changes how the command is installed. Your memories in ~/.config/cortexgraph/ are untouched.
The server includes 7 command-line tools:
cortexgraph # Run MCP server
cortexgraph-migrate # Migrate from old STM setup
cortexgraph-index-ltm # Index Obsidian vault
cortexgraph-backup # Git backup operations
cortexgraph-vault # Vault markdown operations
cortexgraph-search # Unified STM+LTM search
cortexgraph-maintenance # JSONL storage stats and compactionInteractive graph visualization using PyVis:
# Install visualization dependencies
pip install "cortexgraph[visualization]"
# or with uv
uv pip install "cortexgraph[visualization]"
# Or install dependencies manually
pip install pyvis networkx
# Generate interactive HTML visualization
python scripts/visualize_graph.py
# Custom output location
python scripts/visualize_graph.py --output ~/Desktop/memory_graph.html
# Custom data paths
python scripts/visualize_graph.py --memories ~/data/memories.jsonl --relations ~/data/relations.jsonlFeatures:
Interactive network graph with pan/zoom
Node colors by status (active=blue, promoted=green, archived=gray)
Node size based on use count
Edge colors by relation type
Hover tooltips showing full content, tags, and entities
Physics controls for layout adjustment
The visualization reads directly from your JSONL files and creates a standalone HTML file you can open in any browser.
13 tools for AI assistants to manage memories:
Tool | Purpose |
| Save new memory with tags, entities (auto-enrichment in v0.6.0+) |
| Search with filters and scoring (includes review candidates) |
| Unified search across STM + LTM |
| Reinforce memory (boost strength) |
| Record memory usage for natural spaced repetition |
| ✨ NEW v0.6.0 - Detect memory-worthy content, suggest entities/strength |
| ✨ NEW v0.6.0 - Detect recall intent, suggest search queries |
| Garbage collect low-scoring memories |
| Move to long-term storage |
| Find similar memories |
| Merge similar memories (algorithmic) |
| Get entire knowledge graph |
| Retrieve specific memories |
| Link memories explicitly |
Search across STM and LTM with the CLI:
cortexgraph-search "typescript preferences" --tags preferences --limit 5 --verboseBoost a memory's recency/use count to slow decay:
{
"memory_id": "mem-123",
"boost_strength": true
}Sample response:
{
"success": true,
"memory_id": "mem-123",
"old_score": 0.41,
"new_score": 0.78,
"use_count": 5,
"strength": 1.1
}Suggest and promote high-value memories to the Obsidian vault.
Auto-detect (dry run):
{
"auto_detect": true,
"dry_run": true
}Promote a specific memory:
{
"memory_id": "mem-123",
"dry_run": false,
"target": "obsidian"
}As an MCP tool (request body):
{
"query": "typescript preferences",
"tags": ["preferences"],
"limit": 5,
"verbose": true
}Find and merge duplicate or highly similar memories to reduce clutter:
Auto-detect candidates (preview):
{
"auto_detect": true,
"mode": "preview",
"cohesion_threshold": 0.75
}Apply consolidation to detected clusters:
{
"auto_detect": true,
"mode": "apply",
"cohesion_threshold": 0.80
}The tool will:
Merge content intelligently (preserving unique information)
Combine tags and entities (union)
Calculate strength based on cluster cohesion
Preserve earliest created_at and latest last_used timestamps
Create tracking relations showing consolidation history
For a memory with $n_{\text{use}}=1$, $s=1.0$, and $\lambda = 2.673 \times 10^{-6}$ (3-day half-life):
Time | Score | Status |
0 hours | 1.000 | Fresh |
12 hours | 0.917 | Active |
1 day | 0.841 | Active |
3 days | 0.500 | Half-life |
7 days | 0.210 | Decaying |
14 days | 0.044 | Near forget |
30 days | 0.001 | Forgotten |
With $\beta = 0.6$ (sub-linear weighting):
Use Count | Boost Factor |
1 | 1.0× |
5 | 2.6× |
10 | 4.0× |
50 | 11.4× |
Frequent access significantly extends retention.
MCP Tools Reference - Comprehensive documentation for all 18 MCP tools
API Quick Reference - Minimal tool signatures and usage examples
Scoring Algorithm - Complete mathematical model with LaTeX formulas
Smart Prompting - Patterns for natural LLM integration
Architecture - System design and implementation
Multi-Agent System - Consolidation agents and pipeline architecture
Bear Integration - Guide to using Bear app as an LTM store
Graph Features - Knowledge graph usage
3-day half-life
Remember preferences and decisions
Auto-promote frequently referenced information
1-day half-life
Fast context switching
Aggressive forgetting of old context
14-day half-life
Long retention
Comprehensive knowledge preservation
AGPL-3.0 License - See LICENSE for details.
This project uses the GNU Affero General Public License v3.0, which requires that modifications to this software be made available as source code when used to provide a network service.
Model Context Protocol - MCP specification
Ebbinghaus Forgetting Curve - Cognitive science foundation
Basic Memory - Primary inspiration for the integration layer. CortexGraph extends this concept by adding the Ebbinghaus forgetting curve, temporal decay algorithms, short-term memory in JSONL storage, and natural spaced repetition.
Additional research inspired by: mem0, Neo4j Graph Memory
If you use this work in research, please cite:
@software{cortexgraph_2025,
title = {Mnemex: Temporal Memory for AI},
author = {simplemindedbot},
year = {2025},
url = {https://github.com/simplemindedbot/cortexgraph},
version = {0.5.3}
}Contributions are welcome! See CONTRIBUTING.md for detailed instructions.
I develop on macOS and need help testing on Windows and Linux. If you have access to these platforms, please:
Try the installation instructions
Run the test suite
Report what works and what doesn't
See the Help Needed section in CONTRIBUTING.md for details.
For all contributors, see CONTRIBUTING.md for:
Platform-specific setup (Windows, Linux, macOS)
Development workflow
Testing guidelines
Code style requirements
Pull request process
Quick start:
Read CONTRIBUTING.md for platform-specific setup
Understand the Architecture docs
Review the Scoring Algorithm
Follow existing code patterns
Add tests for new features
Update documentation
Version: 1.0.0 Status: Research implementation - functional but evolving
14 MCP tools
Temporal decay algorithm
Knowledge graph
JSONL storage
LTM index
Git integration
Smart prompting documentation
Maintenance CLI
Memory consolidation (algorithmic merging)
Multi-Agent Consolidation Pipeline
DecayAnalyzer, ClusterDetector, SemanticMerge, LTMPromoter, RelationshipDiscovery
Scheduler for orchestration
Beads issue tracking integration
Dry-run and rate limiting support
Natural language activation (v0.6.0+)
Auto-enrichment for entity extraction
Adaptive decay parameters
Performance benchmarks
LLM-assisted consolidation (optional enhancement)
Built with Claude Code 🤖
Cluster similar memories for potential consolidation or find duplicates.
Groups similar memories based on semantic similarity (if embeddings are
enabled) or other strategies. Useful for identifying redundant memories.
Args:
strategy: Clustering strategy (default: "similarity").
threshold: Similarity threshold for linking (uses config default).
max_cluster_size: Maximum memories per cluster (uses config default).
find_duplicates: Find likely duplicate pairs instead of clustering.
duplicate_threshold: Similarity threshold for duplicates (uses config default).
Returns:
List of clusters or duplicate pairs with scores and suggested actions.
| Name | Required | Description | Default |
|---|---|---|---|
| duplicate_threshold | No | ||
| find_duplicates | No | ||
| max_cluster_size | No | ||
| strategy | No | similarity | |
| threshold | 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 the full burden. It discloses behavioral traits such as clustering based on semantic similarity (if embeddings enabled) and returning clusters or duplicate pairs with scores and suggested actions. However, it lacks details on permissions, rate limits, or side effects (e.g., whether clustering modifies 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 appropriately sized and front-loaded, starting with the core purpose, followed by implementation details, and ending with parameter and return explanations. Every sentence earns its place without redundancy, and the structure (purpose → behavior → args → returns) is logical and efficient.
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 (5 parameters, no annotations, but with output schema), the description is largely complete. It covers purpose, behavior, parameters, and return values. However, it lacks explicit guidance on when to choose clustering vs. duplicate finding, and the output schema existence means return details are not strictly needed, but some behavioral context (e.g., side effects) could be enhanced.
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 significant meaning beyond the input schema, which has 0% description coverage. It explains all 5 parameters with clear semantics: 'strategy' as clustering strategy, 'threshold' for similarity linking, 'max_cluster_size' for cluster limits, 'find_duplicates' toggles between clustering and duplicate finding, and 'duplicate_threshold' for duplicate detection. This fully compensates for the schema's lack of descriptions.
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 specific verbs ('cluster similar memories', 'find duplicates') and resources ('memories'), distinguishing it from siblings like 'consolidate_memories' (which likely acts on clusters) and 'search_memory' (which finds individual memories). It explicitly mentions two distinct use cases: clustering for consolidation and finding duplicates.
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 for when to use the tool ('useful for identifying redundant memories'), but does not explicitly state when not to use it or name alternatives among siblings. It implies usage for consolidation or duplicate detection without specifying prerequisites or comparing to tools like 'consolidate_memories'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consolidate similar memories using LLM-driven merging (NOT YET IMPLEMENTED).
This tool will use an LLM to intelligently merge similar memories,
resolve conflicts, and create consolidated notes. Currently returns
a placeholder message.
Args:
cluster_id: Cluster ID to consolidate.
mode: Operation mode - "dry_run" or "apply".
Returns:
Consolidation results (when implemented).
| Name | Required | Description | Default |
|---|---|---|---|
| cluster_id | Yes | ||
| mode | No | dry_run |
| 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. It discloses key behavioral traits: the tool is not yet implemented (returns placeholder), uses LLM-driven merging, and resolves conflicts. However, it doesn't cover important aspects like permissions needed, rate limits, or error handling, leaving gaps 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 well-structured and appropriately sized. It front-loads the purpose, includes implementation status, and lists parameters clearly. Every sentence adds value, though the placeholder note could be slightly more concise.
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 (returns are documented elsewhere) and 2 parameters with 0% schema coverage, the description is moderately complete. It covers purpose, status, and parameters but lacks details on behavioral aspects like permissions or error handling, which are important for a mutation tool with no annotations.
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 explains 'cluster_id' as 'Cluster ID to consolidate' and 'mode' with options 'dry_run' or 'apply,' adding meaningful context beyond the bare schema. However, it doesn't detail what a 'Cluster ID' represents or the implications of each mode, leaving some ambiguity.
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: 'Consolidate similar memories using LLM-driven merging.' It specifies the verb (consolidate), resource (memories), and method (LLM-driven merging). However, it doesn't explicitly differentiate from sibling tools like 'cluster_memories' or 'promote_memory,' which prevents a perfect score.
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 minimal usage guidance. It mentions the tool is 'NOT YET IMPLEMENTED' and currently returns a placeholder, which is useful context. However, it lacks explicit guidance on when to use this tool versus alternatives like 'cluster_memories' or 'promote_memory,' and doesn't specify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an explicit relation between two memories.
Links two memories with a typed relationship (e.g., "references",
"follows_from", "similar_to").
Args:
from_memory_id: Source memory ID.
to_memory_id: Target memory ID.
relation_type: Type of relation.
strength: Strength of the relation (0.0-1.0).
metadata: Additional metadata about the relation.
Returns:
Created relation ID and confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| from_memory_id | Yes | ||
| metadata | No | ||
| relation_type | Yes | ||
| strength | No | ||
| to_memory_id | 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 the tool creates a relation and returns an ID and confirmation, which covers basic behavior. However, it lacks details on permissions needed, whether the operation is idempotent, error conditions (e.g., invalid memory IDs), or side effects (e.g., updating memory graphs). For a mutation tool with zero annotation coverage, this is insufficient.
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 efficiently structured: a concise purpose statement, a brief elaboration with examples, and a well-organized Args/Returns section. Every sentence adds value without redundancy, and information is front-loaded with the core purpose stated first.
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 (mutation with 5 parameters) and the presence of an output schema (which covers return values), the description is partially complete. It explains parameters well but lacks behavioral context (e.g., error handling, idempotency) and usage guidelines. With no annotations, it should do more to guide safe and effective use.
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 provides clear semantic explanations for all 5 parameters (e.g., 'Source memory ID', 'Type of relation', 'Strength of the relation (0.0-1.0)'), adding meaningful context beyond the schema's titles. However, it does not elaborate on relation_type examples beyond the parenthetical list or metadata structure.
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 ('Create an explicit relation') and resource ('between two memories'), with a parenthetical list of example relation types. It distinguishes this from sibling tools like 'cluster_memories' or 'read_graph' by focusing on explicit pairwise linking rather than grouping, analyzing, or retrieving existing relations.
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 when linking two specific memories with a typed relationship, but does not explicitly state when to use this tool versus alternatives like 'cluster_memories' (for grouping) or 'read_graph' (for viewing existing relations). No guidance on prerequisites, exclusions, or common scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform garbage collection on low-scoring memories.
Removes or archives memories whose decay score has fallen below the
forget threshold. This prevents the database from growing indefinitely
with unused memories.
Args:
dry_run: Preview what would be removed without actually removing.
archive_instead: Archive memories instead of deleting.
limit: Maximum number of memories to process.
Returns:
Statistics about removed/archived memories.
| Name | Required | Description | Default |
|---|---|---|---|
| archive_instead | No | ||
| dry_run | No | ||
| 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 the full burden of behavioral disclosure. It explains that the tool 'Removes or archives memories' based on decay scores, which clarifies it's a destructive operation (though with safe options like dry_run and archive_instead). However, it doesn't mention potential side effects, rate limits, or authentication requirements, leaving some behavioral aspects 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 well-structured and appropriately sized. It starts with the core purpose, explains the rationale, lists parameters with clear explanations, and states the return value. Every sentence earns its place with no wasted words, and information is front-loaded effectively.
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 (destructive operation with 3 parameters) and the presence of an output schema (which covers return values), the description is mostly complete. It explains the tool's purpose, parameters, and behavior adequately. The main gap is lack of explicit warnings about destructive nature or prerequisites, though the dry_run parameter provides some safety context.
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 significant semantic value beyond the input schema, which has 0% description coverage. It explains each parameter's purpose: 'dry_run: Preview what would be removed without actually removing,' 'archive_instead: Archive memories instead of deleting,' and 'limit: Maximum number of memories to process.' This fully compensates for the schema's lack of descriptions.
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: 'Perform garbage collection on low-scoring memories' with specific verb ('Perform garbage collection') and resource ('low-scoring memories'). It distinguishes from siblings like 'cluster_memories' or 'consolidate_memories' by focusing on removal/archiving based on decay scores.
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 for when to use this tool: when memories have 'fallen below the forget threshold' to 'prevent the database from growing indefinitely with unused memories.' However, it doesn't explicitly state when NOT to use it or mention alternatives among siblings, though the purpose implies it's for cleanup rather than other memory operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve specific memories by their IDs.
Similar to the reference MCP memory server's open_nodes functionality.
Returns detailed information about the requested memories including
their relations to other memories.
Args:
memory_ids: Single memory ID or list of memory IDs to retrieve.
include_relations: Include relations from/to these memories.
include_scores: Include decay scores and age.
Returns:
Detailed information about the requested memories with relations.
| Name | Required | Description | Default |
|---|---|---|---|
| include_relations | No | ||
| include_scores | No | ||
| memory_ids | 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. It discloses that the tool retrieves memories and returns detailed information with optional relations and scores, which covers basic behavior. However, it lacks details on potential side effects (e.g., whether this is a read-only operation), error handling, or performance aspects like rate limits. The description doesn't contradict annotations, but it's not comprehensive for a tool with no 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 appropriately sized and front-loaded, starting with the core purpose. The sentences are efficient, with no wasted words, and it includes a structured 'Args' and 'Returns' section for clarity. However, the reference to 'open_nodes functionality' could be considered slightly extraneous if not widely understood.
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 3 parameters with 0% schema coverage, the description does a good job of covering the basics. It explains the purpose, parameters, and return intent, making it largely complete for a retrieval tool. Minor gaps include lack of sibling differentiation and deeper behavioral context.
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 significant meaning beyond the input schema, which has 0% description coverage. It explains that 'memory_ids' can be a single ID or list, 'include_relations' adds relations from/to memories, and 'include_scores' includes decay scores and age. This compensates well for the schema's lack of descriptions, though it doesn't fully detail all parameter nuances (e.g., format of IDs).
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 as 'Retrieve specific memories by their IDs' and 'Returns detailed information about the requested memories including their relations to other memories.' This specifies the verb (retrieve) and resource (memories) with scope (by IDs, with relations). However, it doesn't explicitly differentiate from sibling tools like 'read_graph' or 'search_memory' which might also retrieve memory information.
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 minimal usage guidance. It mentions 'Similar to the reference MCP memory server's open_nodes functionality,' which offers some context but is vague. There's no explicit guidance on when to use this tool versus alternatives like 'search_memory' or 'read_graph,' nor any mention of prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote high-value memories to long-term storage.
Memories with high scores or frequent usage are promoted to the Obsidian
vault (or other long-term storage) where they become permanent.
Args:
memory_id: Specific memory ID to promote.
auto_detect: Automatically detect promotion candidates.
dry_run: Preview what would be promoted without promoting.
target: Target for promotion (default: "obsidian").
force: Force promotion even if criteria not met.
Returns:
List of promoted memories and promotion statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| auto_detect | No | ||
| dry_run | No | ||
| force | No | ||
| memory_id | No | ||
| target | No | obsidian |
| 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. It discloses that promotion makes memories 'permanent' and mentions a 'dry_run' option for previewing, which adds behavioral context. However, it doesn't cover critical aspects like permissions needed, rate limits, error handling, or what 'permanent' entails operationally (e.g., irreversible changes).
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 well-structured with a purpose statement, elaboration, and clear sections for Args and Returns. It's appropriately sized with no redundant sentences, though the elaboration could be slightly more concise. Every sentence adds value, and it's front-loaded with the core purpose.
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 5 parameters with 0% schema coverage and no annotations, the description does a good job explaining parameter semantics and the tool's purpose. The presence of an output schema means the description doesn't need to detail return values, which it correctly omits. However, for a tool that makes memories 'permanent', more behavioral context (e.g., side effects, prerequisites) would enhance 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?
Schema description coverage is 0%, so the description must compensate. It provides meaningful semantics for all 5 parameters: 'memory_id' for specific promotion, 'auto_detect' for automatic candidate detection, 'dry_run' for previewing, 'target' for destination (default 'obsidian'), and 'force' to override criteria. This adds substantial value beyond the bare schema, though it doesn't detail parameter interactions (e.g., 'memory_id' vs 'auto_detect').
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: 'Promote high-value memories to long-term storage' with specific criteria (high scores or frequent usage) and destination (Obsidian vault or other storage). It distinguishes from siblings like 'save_memory' or 'consolidate_memories' by focusing on promotion to permanent storage, though it doesn't explicitly contrast with them.
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 when memories have high scores or frequent usage, but doesn't explicitly state when to use this tool versus alternatives like 'save_memory' or 'consolidate_memories'. It mentions 'auto_detect' for automatic candidate detection, providing some contextual guidance, but lacks clear exclusions or prerequisites.
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 of memories and relations.
Returns the complete graph structure including all memories (with decay scores),
all relations between memories, and statistics about the graph.
Args:
status: Filter memories by status - "active", "promoted", "archived", or "all".
include_scores: Include decay scores and age in results.
limit: Maximum number of memories to return.
Returns:
Complete knowledge graph with memories, relations, and statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| include_scores | No | ||
| limit | No | ||
| status | No | active |
| 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. It discloses that the tool reads data (implying non-destructive) and returns a complete graph, but lacks details on permissions, rate limits, or error handling. It adds some context about what's included (decay scores, statistics) but is incomplete for 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 well-structured and front-loaded with the core purpose, followed by parameter and return details. Every sentence adds value without redundancy, making it efficient and easy to parse for an agent.
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 (3 parameters, no annotations, but with an output schema), the description is fairly complete. It covers purpose, parameters, and return values, and the output schema reduces the need to explain returns in detail. However, it lacks usage guidelines and some behavioral context, slightly impacting 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 schema description coverage is 0%, so the description must compensate. It explains all three parameters: status filters memories by specific values, include_scores adds decay scores and age, and limit sets a maximum return count. This adds meaningful semantics beyond the bare schema, though it could elaborate on default behaviors or constraints.
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 verb 'Read' and the resource 'entire knowledge graph of memories and relations', specifying it returns the complete graph structure including memories with decay scores, relations, and statistics. This distinguishes it from siblings like search_memory or cluster_memories by emphasizing comprehensive retrieval rather than filtering or processing.
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 does not mention scenarios where this is preferred over search_memory or open_memories, nor does it specify prerequisites or exclusions, leaving the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a new memory to short-term storage.
The memory will have temporal decay applied and will be forgotten if not used
regularly. Frequently accessed memories may be promoted to long-term storage
automatically.
Args:
content: The content to remember.
tags: Tags for categorization.
entities: Named entities in this memory.
source: Source of the memory.
context: Context when memory was created.
meta: Additional custom metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| context | No | ||
| entities | No | ||
| meta | No | ||
| source | No | ||
| tags | 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 the full burden of behavioral disclosure. It effectively describes key behavioral traits: the memory is stored in 'short-term storage' with 'temporal decay,' may be 'forgotten if not used regularly,' and 'frequently accessed memories may be promoted to long-term storage automatically.' This provides important context about persistence, lifecycle, and automatic promotion that isn't obvious from the tool name alone.
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 appropriately sized with three sentences followed by a structured parameter list. The first sentence states the core purpose, the next two explain behavioral context, and the Args section efficiently documents parameters. There's minimal waste, though the parameter explanations could be slightly more detailed without losing conciseness.
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 (6 parameters, behavioral nuances) and the absence of annotations, the description does a reasonably complete job. It explains the tool's purpose, behavioral characteristics (decay, promotion), and documents all parameters. Since there's an output schema (mentioned in context signals), the description doesn't need to explain return values. The main gap is lack of explicit guidance on when to use versus 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 description includes an 'Args:' section that lists all 6 parameters with brief explanations, adding meaning beyond the input schema which has 0% description coverage. However, the explanations are minimal (e.g., 'Tags for categorization') and don't provide detailed semantics like format examples, constraints, or relationships between parameters. Since schema coverage is 0%, the description compensates somewhat but not fully.
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 ('Save a new memory') and resource ('to short-term storage'), providing a specific verb+resource combination. It distinguishes this from sibling tools like 'promote_memory' or 'touch_memory' by focusing on initial creation rather than manipulation of existing memories. However, it doesn't explicitly contrast with 'create_relation' which might also create new data.
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 context through phrases like 'temporal decay applied' and 'forgotten if not used regularly,' suggesting this is for transient storage. However, it doesn't explicitly state when to use this tool versus alternatives like 'promote_memory' (for long-term storage) or 'cluster_memories' (for grouping). No explicit when-not-to-use guidance or named alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for memories with optional filters and scoring.
Args:
query: Text query to search for.
tags: Filter by tags.
top_k: Maximum number of results.
window_days: Only search memories from last N days.
min_score: Minimum decay score threshold.
use_embeddings: Use semantic search with embeddings.
Returns:
List of matching memories with scores.
| Name | Required | Description | Default |
|---|---|---|---|
| min_score | No | ||
| query | No | ||
| tags | No | ||
| top_k | No | ||
| use_embeddings | No | ||
| window_days | 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 for behavioral disclosure. While it mentions optional filters and scoring, it doesn't describe important behavioral aspects like whether this is a read-only operation, what permissions are required, how results are sorted, or what happens with null parameters. The mention of 'decay score threshold' hints at some scoring mechanism but doesn't explain it.
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 well-structured with clear sections for Args and Returns. It's appropriately sized for a 6-parameter tool, though the opening sentence could be more specific about what type of search this performs (semantic vs keyword).
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 6 parameters with no schema descriptions and no annotations, the description provides basic parameter semantics and return format. However, for a search tool with complex filtering options and sibling alternatives, it lacks sufficient context about behavioral characteristics, performance considerations, and differentiation from other search tools on the server.
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 0% schema description coverage, the description provides basic semantic information for all 6 parameters in the Args section, explaining what each parameter controls. However, it doesn't provide deeper context about parameter interactions, default behaviors, or practical examples of how to use them effectively together.
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 searches for memories with optional filters and scoring, providing a specific verb (search) and resource (memories). However, it doesn't differentiate from sibling tools like 'search_unified' or 'open_memories', which appear to be related search 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 provides no guidance on when to use this tool versus alternatives like 'search_unified' or 'open_memories'. It mentions optional filters but gives no context about appropriate use cases or when other tools might be more suitable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across both STM and LTM with unified ranking.
Args:
query: Text query to search for.
tags: Filter by tags.
limit: Maximum total results.
stm_weight: Weight multiplier for STM results.
ltm_weight: Weight multiplier for LTM results.
window_days: Only include STM memories from last N days.
min_score: Minimum score threshold for STM memories.
Returns:
A dictionary containing the search results.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| ltm_weight | No | ||
| min_score | No | ||
| query | No | ||
| stm_weight | No | ||
| tags | No | ||
| window_days | No |
| 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 mentions 'unified ranking' but doesn't explain what this means operationally, how results are combined, or any behavioral traits like performance characteristics, error conditions, or limitations. The description is minimal beyond basic functionality.
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 efficiently structured with a clear purpose statement followed by organized parameter and return sections. Every sentence earns its place, and the information is front-loaded with the core functionality stated first.
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 (7 parameters, no annotations) but with an output schema present, the description covers parameters adequately but lacks behavioral context. It doesn't explain how STM and LTM differ, what 'unified ranking' entails, or provide usage examples. The output schema handles return values, but more operational guidance would be helpful.
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 0% schema description coverage, the description compensates well by listing all 7 parameters with brief explanations. It clarifies what each parameter controls (e.g., 'Weight multiplier for STM results', 'Only include STM memories from last N days'), adding meaningful context beyond the schema's type 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 searches across STM and LTM with unified ranking, providing a specific verb ('search') and resources ('STM and LTM'). However, it doesn't explicitly differentiate from sibling tools like 'search_memory' or 'open_memories', which appear related to memory 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?
No guidance is provided on when to use this tool versus alternatives like 'search_memory' or 'open_memories'. The description only states what the tool does, not when it's appropriate or what distinguishes it from similar tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reinforce a memory by updating its last accessed time and use count.
This resets the temporal decay and increases the memory's resistance to
being forgotten. Optionally can boost the memory's base strength.
Args:
memory_id: ID of the memory to reinforce.
boost_strength: Whether to boost the base strength.
Returns:
Updated memory statistics including old and new scores.
| Name | Required | Description | Default |
|---|---|---|---|
| boost_strength | No | ||
| memory_id | 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 effectively describes the tool's effects ('resets temporal decay', 'increases resistance to being forgotten', 'optionally boost base strength') and the return value ('updated memory statistics including old and new scores'). It doesn't cover potential side effects, rate limits, or error conditions, but provides solid operational context.
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 well-structured and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds value: explaining effects, documenting parameters, and describing returns. There's no wasted text, and it efficiently communicates essential information in four concise sentences.
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 moderate complexity with 2 parameters, the description is reasonably complete. It covers purpose, effects, parameters, and returns at a high level. However, it lacks details on error cases, side effects, or specific usage scenarios that would be helpful 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?
The schema description coverage is 0%, so the description must compensate. It adds meaningful context for both parameters: 'memory_id' is explained as 'ID of the memory to reinforce', and 'boost_strength' as 'Whether to boost the base strength' with the optional nature clarified. This goes beyond the schema's basic type information, though it could provide more detail on what boosting entails.
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 specific verbs ('reinforce', 'updating', 'resets', 'increases') and identifies the resource ('memory'). It distinguishes this from siblings like 'promote_memory' or 'save_memory' by focusing on temporal reinforcement rather than creation or promotion.
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 context through phrases like 'resets the temporal decay' and 'increases resistance to being forgotten', suggesting it's for maintaining memory relevance. However, it doesn't explicitly state when to use this tool versus alternatives like 'promote_memory' or 'consolidate_memories', nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no significant overlap. For example, cluster_memories groups similar memories, consolidate_memories merges them, create_relation links memories, and touch_memory reinforces a single memory. The descriptions clearly differentiate each tool's function, making misselection unlikely.
The naming follows a consistent verb_noun pattern throughout (e.g., cluster_memories, create_relation, promote_memory), with all tools using snake_case. The only minor deviation is 'gc' (garbage collection), which is an acronym rather than a descriptive verb_noun, but it's a common term in this context and doesn't break overall consistency.
With 11 tools, the count is well-scoped for a memory management system. Each tool serves a specific purpose in the lifecycle of memories (e.g., save, search, reinforce, promote, garbage collect), and none feel redundant or unnecessary for the domain.
The toolset provides comprehensive coverage for memory management, including creation (save_memory), retrieval (open_memories, search_memory, search_unified), reinforcement (touch_memory), organization (cluster_memories, create_relation), promotion (promote_memory), and cleanup (gc). The only minor gap is that consolidate_memories is noted as 'NOT YET IMPLEMENTED', but this is explicitly documented, and other tools cover related functionality.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Long-term memory for AI assistants. Isolated per-user storage, recall across conversations.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Long-term memory for AI assistants. Hybrid retrieval, query expansion, auto-topics.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/prefrontal-systems/cortexgraph'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
