Skip to main content
Glama
leonardsellem

Hypermnesic

by leonardsellem
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

hypermnesic

CI PyPI License: AGPL v3

One brain. Every AI. Yours.

Your second brain lives as plain Markdown in a Git repo you host. ChatGPT, Claude, and your coding agents — on your laptop and your phone — all read and write that same brain through one endpoint. Obsidian is how you browse it.

Here's the part that matters: because every AI keeps curating the same notes, your memory doesn't just persist — it compounds. Every fact captured, every correction, every link added makes the next answer from every assistant sharper. Per-app memory traps you in silos; one shared brain gets smarter each day — and it's plain files you own, not rows in a vendor's database.

An agent writes a memory through the MCP commit_note tool, git log shows the resulting real commit, and a fresh session recalls and cites it

Every memory is a real Git commit — reviewable, revertible, yours. The search index is a disposable projection of your files; delete it and rebuild it any time. A reindex can never lose a memory.

Who it's for: developers and power note-takers who want durable agent memory they own — plain files in their own Git history, reachable by every assistant, with no vendor lock-in.

Status: public v0.1.0 release. The engine is licensed under AGPL-3.0-only; the companion plugin ships from the separate GPL-3.0 hypermnesic-companion repository.

Related MCP server: auxly-memory-cli

Why it compounds

Five surfaces — ChatGPT, Claude, Codex, your own agent, and Obsidian — arranged around a central web of linked Markdown notes; loose terracotta arrows sweep clockwise through four stages: Capture, Curate, Recall, Compound

Per-app memory fragments: what you told ChatGPT is invisible to Claude, your phone's assistant forgets what your laptop's agent learned, and none of it is yours to move. A shared brain does the opposite — it turns every interaction into a flywheel:

  • Capture — any AI writes a note: a decision, a fact, a person, a meeting.

  • Curate — any AI links it, corrects it, or adds context the next time it's relevant.

  • Recall — every other AI retrieves it on the next question.

  • Compound — the brain grows denser and more useful with every turn, for all of them.

Because every write is a reviewable Git commit, one assistant's curation is safe, visible, and revertible for all the others. The brain is shared and trustworthy.

One endpoint, every client

One self-hosted MCP endpoint serves every client — ChatGPT, Claude, the Claude Code / Codex plugin, and a read-only Obsidian companion — the same way

Point any MCP-capable app at your endpoint URL and it just works — OAuth is automatic (log in through the browser once, then silent refresh):

  • ChatGPT, Claude (desktop, mobile, web) — add a custom connector.

  • Claude Code / Codex — the bundled plugin.

  • Your own agents — any MCP client, same URL.

  • Obsidian — a read-only companion over your tailnet, for browsing and serendipity.

On the machine that holds the vault, skip the network entirely and use the hypermnesic CLI. Setup details are in the Quick start below.

How it's different

Most "agent memory" keeps your memories in their store. hypermnesic keeps them as plain Markdown in your Git repo; the search index is a throwaway projection you can delete and rebuild at will. Everything else follows from that one choice.

Question

Hypermnesic

Hosted memory layers

Source of truth

Markdown files in your Git repo

Service-managed memory store

Writes

Git-first commits — reviewable, revertible

API/app-managed writes

Reach

One self-hosted OAuth endpoint every client shares

Per-product API or app feature

Compounding

Every AI curates one shared brain

Memory siloed per app

How it sits next to tools you may know:

  • mem0 / Zep — memory APIs over a managed vector (and graph) store. Reach for them if you want a hosted memory service; reach for hypermnesic if you want your files to be the memory.

  • Hindsight — also open-source agent memory, but it lives in its own vector store you run via Docker/cloud, and it posts a higher LongMemEval score on a more lenient judge axis. hypermnesic optimizes for owned, auditable, compounding files, not a leaderboard rank — read the honest comparability envelope in harness/BENCHMARKS.md.

  • Honcho — complementary, not competing. Honcho models who you are (preferences, style, theory-of-mind); hypermnesic holds what you know, in files. Use both.

  • A database-backed personal brain — I built one before this. The database drifted from the files, and I couldn't fully trust or move it. hypermnesic is the rebuild: files are truth, the index is disposable.

Full tool-by-tool detail — including when hypermnesic is the wrong fit — is in why hypermnesic.

Try it in under 5 minutes

uv tool install hypermnesic
hypermnesic local-proof --demo-dir /tmp/hypermnesic-demo

That creates a tiny Markdown git repo, projects it into the disposable index, recalls the repo-relative source note, and previews the exact commit_note write diff without writing it. No account, no service.

Terminal demo: hypermnesic local-proof shows source-grounded recall and a dry-run write diff

The demo source is an asciinema cast. It uses only a generated /tmp/hypermnesic-demo vault and placeholder-safe paths.

Quick start

A. Prove local memory works

Start on the machine that holds the vault. You need only a git repo of markdown notes. Dense embeddings improve ranking when OPENAI_API_KEY is configured, but the proof also works offline in lexical mode.

# 1. install the engine from PyPI
uv tool install hypermnesic

# 2. prove recall from your own markdown files, with a dry-run write preview
hypermnesic local-proof /path/to/your/vault

# or try a tiny generated demo vault first
hypermnesic local-proof --demo-dir /tmp/hypermnesic-demo

The proof path validates a git-backed vault, projects committed markdown files into the disposable .hypermnesic/ index, asks a natural-language question, returns the repo-relative source markdown path, and shows a commit_note dry-run diff without creating a write commit. The success milestone is Local memory works.

B. Self-host the endpoint

After the local proof succeeds, bring the shared endpoint online for remote apps. You need Tailscale installed and logged in (tailscale up); hypermnesic uses Tailscale Funnel for public HTTPS + automatic TLS, so there is no reverse proxy or cert to manage.

hypermnesic setup /path/to/your/vault \
  --public-url https://<your-host>.ts.net/mcp

# later, diagnose without changing services, secrets, funnel routes, or git
hypermnesic doctor /path/to/your/vault \
  --public-url https://<your-host>.ts.net/mcp

setup renders + starts a user service, generates an owner-only consent secret (~/.config/hypermnesic-cloud/cloud.env, chmod 600), configures the Tailscale funnel (the /mcp mount + the OAuth discovery well-knowns), then verifies the live HTTPS discovery chain before reporting success. Re-running it converges to the same state. It prints milestone checks, your endpoint URL, and login instructions. --resource defaults to --public-url; pass it only when the OAuth resource identifier differs. doctor and status report local index health, remote reach, OAuth discovery, auth challenge, write availability, dense key source/state, vector coverage, and client-specific next actions without mutating state. Read tools also expose degraded_reason; after an embedding 429 they cool down provider calls while continuing to serve lexical/graph results. Dense key lookup is repo-scoped: process OPENAI_API_KEY wins, otherwise the target vault's gitignored .env is used even when the command or MCP server starts from another working directory. Live OpenAI smoke checks stay opt-in with --check-dense-live. Dense diagnostics keep credential state separate from projection state: missing indexes point to initialization, and stale/absent vectors point to hypermnesic converge /path/to/vault --now --json before a full reindex. By default, new OAuth clients request read; admins can make new approvals request both read and write with --default-client-scopes read write or HYPERMNESIC_DEFAULT_CLIENT_SCOPES=read,write. Cloud access tokens last 48 hours (HYPERMNESIC_TOKEN_TTL_SECONDS / --token-ttl); refresh stays 30 days.

C. Connect a client (any remote app)

Point the app's MCP server at your endpoint URL — that's it. OAuth is automatic:

  • Claude / ChatGPT (cloud connectors), Claude Code plugin, Codex: add the MCP server URL https://<your-host>.ts.net/mcp. On first connect the app discovers the OAuth server, opens a browser once for you to authorize, then silently refreshes. The OAuth metadata supports both confidential clients and public clients registered without a client secret.

  • Read vs. write: read access is the default unless the endpoint admin configures --default-client-scopes read write / HYPERMNESIC_DEFAULT_CLIENT_SCOPES=read,write. To grant the commit_note write tool, approve write on the consent page (type your approval token from ~/.config/hypermnesic-cloud/cloud.env). The consent page shows exactly which scopes you're granting, lets you reject or cancel, and explains how to revoke later.

  • Client control: after authorization, inspect or revoke known grants on the engine host with hypermnesic clients list /path/to/vault and hypermnesic clients revoke /path/to/vault <grant-id> --apply.

  • Claude Code / Codex plugin: install the plugin in plugin/ and set HYPERMNESIC_MCP_URL to your endpoint — the bundled .mcp.json is discovery-only and carries no host or token. See plugin/README.md.

  • Obsidian companion: read-only over your tailnet — point it at the tailnet read route http://<tailnet-ip>:8848/mcp (no OAuth; tailnet membership is the boundary). It ships from the public hypermnesic-companion repository under GPL-3.0-or-later; the first companion release is 0.3.0. See obsidian-plugin/README.md and the license boundary below.

D. Use it locally (on the engine host)

The host that runs the engine skips the network entirely and uses the CLI:

hypermnesic local-proof /path/to/vault                           # first local value proof
hypermnesic retrieve /path/to/vault "what do we know about X"   # hybrid search
hypermnesic think    /path/to/vault "topic"                     # thinking-mode
hypermnesic resolve  /path/to/vault "Some Entity"               # name → page path
hypermnesic commit-note /path/to/vault notes/x.md --body "…"    # git-first write (dry-run preview)
hypermnesic memory list /path/to/vault                          # inspect/control memory
hypermnesic memory forget /path/to/vault notes/bad.md            # preview source removal
hypermnesic clients list /path/to/vault                         # inspect OAuth client grants

E. Know what belongs in Hypermnesic

Hypermnesic is for durable project memory: source-grounded facts, decisions, procedures, raw captures, generated summaries with citations, and current-state mirrors that should survive the current session as markdown/git truth.

It is not the default home for short-lived session state or behavioural preferences. For example, "user likes terse replies" belongs in Honcho or another adjacent behavioural memory layer by default, not in Hypermnesic. Secrets, credentials, private keys, bearer tokens, and unreviewed sensitive material should not be written at all.

Before writing, preserve raw evidence or cite source paths. If the destination is unclear, discover writable locations first (list_folders / hypermnesic list-folders); that discovery also returns direct root-local AGENTS.md guidance, or fallback CLAUDE.md guidance, for the requested root when present, with local absolute paths and endpoint URLs redacted from the returned guidance. See the memory taxonomy guide.

F. Run the daily loop

For daily work, use the loop capture -> triage -> recall -> write -> review -> clean up.

hypermnesic capture /path/to/your/vault "raw observation"
hypermnesic daily-review /path/to/your/vault

The daily review is a generated, review-gated dashboard proposal that shows capture backlog, recent writes, generated surfaces, recall-mode reminders, degraded/offline state, and cleanup next actions. See daily workflows.

How it works

A hybrid retrieval engine over a git-tracked markdown corpus, a git-first write path, and the surfaces built on top:

  • Hybrid retrieval — SQLite FTS5 (lexical) fused with sqlite-vec KNN (dense; OpenAI text-embedding-3-large at 1536 dims) via RRF, degrading gracefully to lexical-only when embeddings are down.

  • Read-time convergence — every read first catches the index up to HEAD, invalidates doc-surface vectors for changed markdown files, and closes a bounded slice of the dense lag for chunks and doc surfaces, so recall stays fresh without a manual reindex.

  • Two serving lanes —

    1. a single public OAuth MCP endpoint at /mcp (Tailscale-funnel'd HTTPS; OAuth 2.1 with DCR + PKCE; read tools always, the gated commit_note write tool by scope), used by every remote client the same way;

    2. a tailnet read companion (:8848, auth-off) for the Obsidian companion and the proactive per-prompt hook on tailnet devices.

    By default a write-enabled serve requires OAuth (write_enabled ⇒ auth-required). The advanced --allow-tailnet-write opt-in accepts tailnet membership itself as the write boundary — permitting an auth-off, write-enabled serve, but only on a Tailscale CGNAT address (100.64.0.0/10). A non-tailnet bind is still refused (it would be a public write hole), and every commit_note guard (the blocklist write surface, protected-path refusal, diff-or-die gate, audit log) still applies. Use it only when the tailnet is your trust boundary and the public OAuth lane carries all untrusted traffic.

  • Write path — commit_note takes a caller-supplied repo-relative path and commits it to git through a diff-or-die frontmatter gate and a blocklist write guard (write-anywhere-under-guards: a note may land anywhere in the vault except the protected classes — .git/, .github/, agent-instruction files like CLAUDE.md/AGENTS.md, scripts//hooks//skills/, and build/CI/credential files — which are refused regardless of any allowlist), single-writer locks, and an append-only audit log. An explicit allowlist is an opt-in way to narrow the surface, not the default guard. The index follows as a projection — a reindex never loses a write. Write requires auth (write_enabled ⇒ auth-required).

  • Memory control — hypermnesic memory lists and inspects remembered files, exports markdown plus provenance, previews and applies git-backed forget/delete, reverts safe recent single-file writes, shows audit/refusal history, and answers what an agent may write using the same guard as commit_note.

  • Client control — hypermnesic clients lists secret-free OAuth grant metadata and revokes grants without exposing bearer tokens, refresh tokens, approval credentials, or client secrets. The public cloud lane separately stores restart-survivable OAuth runtime state in owner-only .hypermnesic/cloud-oauth-state.json.

  • Security — operator-consent gates the write scope at login; audience-bound tokens (RFC 8707); refresh rotation + whole-grant revoke; a per-request consent CSP. See docs/2026-06-03-unified-write-anywhere-security-review.md.

  • Human surfaces — thinking-mode, salience + spaced-review digest, serendipity connections, an always-organized navigation surface, frictionless capture→triage, multi-format sidecar extraction (PDF/DOCX/XLSX/PPTX/PNG), and a read-only Obsidian companion.

Benchmarks

LongMemEval V1 accuracy on the comparable gpt-4o-2024-08-06 judge axis: no-memory 60.2, Zep 71.2, Mastra 84.2, hypermnesic 83.2 with a GPT-4o reader and 88.6 with a GPT-4.1 reader; the GPT-4.1-judged rows OMEGA 95.4 and Mastra 94.9 are shown separately as not directly comparable

On LongMemEval V1 (the _s 500-question set), hypermnesic's end-to-end QA accuracy is 88.6% overall / 90.2% task-averaged with a GPT-4.1 reader, and 83.6 / 87.1 with a GPT-4o reader — both graded by the canonical gpt-4o-2024-08-06 judge. Session-level retrieval recall@10 is 0.949 (every gold session in the top-10 for 94.9% of questions).

Read these honestly. They are on the matched GPT-4o-judge axis — the only apples-to-apples memory-system comparison — where hypermnesic sits on par with Mastra Observational Memory (84.2), +12 over Zep (71.2), and +23 over the no-memory full-context floor (60.2). They are not comparable to the GPT-4.1-judged ~95% leaderboard rows — that gap is judge leniency, not memory quality. The full methodology, comparability envelope, per-ability tables, corrections log, and a re-runnable harness (pinned dataset hash; bench extra required for the paid reader path) are in harness/BENCHMARKS.md.

LongMemEval measures retrieval quality. It does not prove setup, consent, memory control, or remote-client operability. Product operability is gated by the local product smoke (scripts/product_smoke.py), offline remote-contract tests, the remote-client smoke checklist, and the first-class product readiness checklist.

Docs

Start with the documentation index. Highlights:

Community

  • Welcome discussion — project overview, support boundaries, and contribution entry points.

  • Public roadmap — near-term launch work, contribution funnel, and current non-goals.

Develop

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run python scripts/license_scan.py   # zero AGPL/GPL/SSPL *dependency* gate

Credentials

The OpenAI key is read from OPENAI_API_KEY (env var or a gitignored repo-root .env). It is never written to the index, the audit log, or any output. The OAuth consent secret lives only in an owner-only env file. Public-lane OAuth client/token runtime state is stored in owner-only .hypermnesic/cloud-oauth-state.json so clients can refresh across service restarts; it is never logged or committed.

License

Hypermnesic is licensed under AGPL-3.0-only. See LICENSE.

The scripts/license_scan.py "zero AGPL/GPL/SSPL" gate is dependency-scoped: it governs hypermnesic's third-party dependencies, keeping the dependency tree copyleft-free. It does not govern — and is not contradicted by — the engine's own AGPL license: the gate excludes the project's own distribution before classifying, so it stays green when the engine itself is licensed AGPL-3.0. Third-party dependencies are permissive and verified copyleft-free on every CI run.

Engine ↔ companion license boundary. The Obsidian companion ships from a separate repository under GPL-3.0; the engine is licensed under AGPL-3.0-only. Neither is a derivative of the other, and that holds because they are separate processes that communicate only at arm's length over the MCP network protocol (search / build_context / think), with no shared or statically-linked code. The boundary stays true only while the companion does not vendor, import, or statically link engine source (the read-only-over-the-wire invariant). Keep that condition and the two licenses remain independent.

Available Tools

7 tools
build_contextA
Read-only

Pages reachable from a page via body wikilinks (in+out edges).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRepo-relative path of the note to expand from.
depthNoNumber of wikilink hops to traverse (in + out edges).

Output Schema

ParametersJSON Schema
NameRequiredDescription
depthYes
startYes
contextYes
manual_reindex_recommendedYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark readOnlyHint=true. The description adds meaningful behavioral context: traversal of in+out edges, depth as number of hops. This goes beyond the annotation's safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the purpose with no wasted words. Every part is essential.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 2 parameters, existing output schema, and readOnlyHint annotation, the description is fully complete. It explains the core graph traversal behavior without needing extra detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with good parameter descriptions. The description adds 'in+out edges' and 'wikilink hops' context, enriching meaning beyond the schema's text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds pages reachable via body wikilinks (in+out edges). It is specific, uses a clear verb+resource, and distinguishes from sibling tools like hypermnesic_search or read_note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for exploring wikilink connections but does not explicitly state when to use this tool versus alternatives like hypermnesic_search. There is no when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_foldersA
Read-only

Discover the vault's folder taxonomy + writable locations before placing a note: child folders under root (drill-down) to depth levels, each with its writability, protected reason, and recursive note count, plus direct root-local AGENTS.md/CLAUDE.md guidance when present. Read-only; the writable flag matches what commit_note accepts. Narrow root to drill deeper when truncated is true.

ParametersJSON Schema
NameRequiredDescriptionDefault
rootNoRepo-relative folder to drill down from ('' = vault root).
depthNoNumber of folder levels to descend.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rootYes
depthYes
foldersYes
omittedYes
truncatedYes
agent_instructionYes
manual_reindex_recommendedYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states 'Read-only', matching the readOnlyHint annotation. It details what the tool returns (writability, protected reason, note count, guidance files) and how writable flag aligns with commit_note, providing full behavioral transparency beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each adding value. It could be slightly tighter, but it is well-structured with the main purpose first, followed by details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple input schema (2 optional parameters) and the existence of an output schema, the description covers what the tool retrieves (hierarchy, writability, counts, guidance) and its read-only nature, making it complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning: root is repo-relative ('' = vault root), depth is levels to descend, and it explains how to use root when truncated is true, offering context beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's purpose: discovering folder taxonomy and writable locations. It specifies details like child folders under root, depth levels, writability, protected reasons, and note counts, which distinguishes it from sibling tools like search or read_note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using it 'before placing a note' and mentions narrowing root when truncated is true. It lacks explicit alternatives or when-not-to-use guidance, but the context is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_noteA
Read-only

Read the full markdown content of a single note by its repo-relative path (typically a path returned by search, resolve, or build_context). Read-only and bounded to indexed notes: a path that is not a committed note in the vault returns found: false with content: null, never an out-of-vault or traversal read. Use it to fetch a note's body after locating it with the other read tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRepo-relative path of the note to read, e.g. 'notes/topic.md' (typically a `path` from a search/resolve/build_context result).

Output Schema

ParametersJSON Schema
NameRequiredDescription
pathYes
foundYes
contentYes
manual_reindex_recommendedYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true; description adds valuable behavioral detail: returns found:false with content:null for non-indexed paths, never does traversal reads.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, front-loaded with the key action and context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter and existing output schema, the description fully covers behavior (success and failure cases) and usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; description adds context by noting the path typically comes from other tools, enhancing meaning beyond the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it reads full markdown content by repo-relative path, distinguishing it from sibling tools like search and resolve which are for locating notes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use after locating with search/resolve/build_context, and states what it does not do (out-of-vault reads), providing clear when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolveA
Read-only

Entity resolution: resolve a name to an existing page path (gbrain's get role), or null if ambiguous/missing. The caller strips .md (use slug) to form a wikilink target.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesEntity or page name to resolve to a vault path.

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
slugYes
resolvedYes
manual_reindex_recommendedYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. Description adds that it returns null if ambiguous/missing, which is important behavioral detail. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste. Purpose stated first, then usage hint. Highly efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (single param, output schema present, annotations provided), the description is complete. It covers return behavior and a practical usage note.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with description for the single parameter 'name'. The description adds no further parameter-specific details, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool resolves a name to an existing page path (like gbrain's get role) or returns null if ambiguous/missing. It distinguishes itself from sibling tools by focusing on entity resolution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage hint: 'The caller strips .md (use slug) to form a wikilink target.' This guides correct invocation. No explicit when-not-to-use, but context with siblings implies alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

thinkA
Read-only

Thinking-mode: related notes + Socratic prompts + related-but-not-yet-linked pairs. Pass the active note's path to exclude it from its own results. Never writes (wrote: false).

ParametersJSON Schema
NameRequiredDescriptionDefault
kNoMaximum number of related notes to return.
pathNoRepo-relative path of the active note to exclude from its own results.
depthNoGraph hops used to expand related notes.
topicYesTopic or question to explore.

Output Schema

ParametersJSON Schema
NameRequiredDescription
noteYes
topicYes
wroteYes
contextYes
relatedYes
unlinkedYes
questionsYes
degraded_reasonYes
degraded_lexical_onlyYes
manual_reindex_recommendedYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, and the description reinforces 'Never writes (wrote: false)'. It adds context about the return type (related notes, prompts, pairs) and the path parameter's effect, going beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both front-loaded with core purpose and a key usage hint. No filler, every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential behavioral context: output type, read-only nature, and path exclusion. With an output schema present, it does not need to detail return format further. Adequate for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description only reiterates the path usage, adding minimal value beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool's purpose: retrieve related notes, generate Socratic prompts, and identify related-but-not-yet-linked pairs. It uses specific, action-oriented language that distinguishes it from sibling tools like search or build_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description explicitly advises to pass the active note's path to exclude it from results, and clarifies that the tool never writes. However, it does not directly compare to alternatives or specify when not to use it over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.0.2
    • Changedbuild_context2 fields changed
      • addedInput schema / properties / depth / description
        Added value: +"Number of wikilink hops to traverse (in + out edges)."
      • addedInput schema / properties / path / description
        Added value: +"Repo-relative path of the note to expand from."
    • Changedhypermnesic_search2 fields changed
      • addedInput schema / properties / k / description
        Added value: +"Maximum number of ranked hits to return."
      • addedInput schema / properties / query / description
        Added value: +"Natural-language query to recall notes by."
    • Changedlist_folders2 fields changed
      • addedInput schema / properties / depth / description
        Added value: +"Number of folder levels to descend."
      • addedInput schema / properties / root / description
        Added value: +"Repo-relative folder to drill down from ('' = vault root)."
    • Addedread_note
    • Changedresolve1 field changed
      • addedInput schema / properties / name / description
        Added value: +"Entity or page name to resolve to a vault path."
    • Changedsearch2 fields changed
      • addedInput schema / properties / k / description
        Added value: +"Maximum number of ranked hits to return."
      • addedInput schema / properties / query / description
        Added value: +"Natural-language query to recall notes by."
    • Changedthink4 fields changed
      • addedInput schema / properties / depth / description
        Added value: +"Graph hops used to expand related notes."
      • addedInput schema / properties / k / description
        Added value: +"Maximum number of related notes to return."
      • addedInput schema / properties / path / description
        Added value: +"Repo-relative path of the active note to exclude from its own results."
      • addedInput schema / properties / topic / description
        Added value: +"Topic or question to explore."
  2. 6 tool updatesv1.0.0
    • First observedbuild_context
    • First observedhypermnesic_search
    • First observedlist_folders
    • First observedresolve
    • First observedsearch
    • First observedthink
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation2/5

There are two tools that perform identical search functionality (search and hypermnesic_search), creating ambiguity about which to use. Other tools are distinct but the overlap is confusing.

Naming Consistency4/5

Most tools follow a verb or verb_noun pattern with consistent lowercase underscore naming. The hypermnesic_search is a namespaced alias that deviates from the pattern, but it is still clear.

Tool Count5/5

With 7 tools covering read-only operations like search, read, resolve, list, and context building, the count is well-scoped for a read-focused knowledge vault assistant.

Completeness2/5

The tool set lacks any write operations such as creating or updating notes. This is a significant gap for a personal knowledge management system, as agents cannot record new information or modify existing notes.

Maintenance

ActivityActive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • elefante

    amenophis1er
    A
    license
    Not graded
    quality
    C
    maintenance
    Open, Git-native memory protocol for MCP agents: stores memories as Markdown files in a Git repo, enabling portability, auditability, and human-editable memory across different AI agents.
    68
    15
    MIT

  • auxly-memory-cli

    Tzamun-Arabia-IT-Co
    A
    license
    Not graded
    quality
    A
    maintenance
    Local-first, file-based memory layer for AI agents — one shared Markdown vault across Claude, Codex, Gemini, Cursor and any MCP client. Provides read/write memory tools with an audit trail, per-agent trust levels, and Git sync; no cloud and no lock-in.
    2
    MIT

  • mem-universe

    H1an1
    A
    license
    A
    quality
    C
    maintenance
    Self-hosted MCP memory server that gives a multi-agent fleet one shared, git-backed memory for search, read, and write.
    8
    1
    MIT

  • Engram

    rwnalds
    A
    license
    A
    quality
    A
    maintenance
    A self-hosted MCP server that gives AI agents shared, long-term memory over a git-backed folder of markdown, enabling persistent knowledge search, read, and write without a database.
    16
    21
    11
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/leonardsellem/hypermnesic'

If you have feedback or need assistance with the MCP directory API, please join our Discord server