keepygaga
Keepygaga is an eight-tool MCP server that lets coding agents read and update a small, shared Markdown core memory (profile, preferences, topics, areas, and people) under explicit constraints.
list: return a live route catalog for topics, areas, or people
read: read up to 15 canonical page paths, including Facts, opaque versions, and capacity signals
create: create new dynamic topic/area/people pages with description, aliases, and Facts
add: append independent Facts to an existing page and optionally replace its description
update: replace an exact Fact, update page metadata or aliases, or mechanically repair a page
move: move exact Facts between source and existing or new destination pages
rename: rename dynamic pages
delete: delete exact Facts or whole dynamic pages, only after explicit current-turn user authorization
Allows Hermes agents to use the same shared core memory, letting them read and update durable user facts and memory pages across sessions and hosts.
Click on "Deploy 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., "@keepygaga Remember that I prefer meetings in the morning."
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.
Keepygaga
A small, deliberate core memory shared by every coding agent.
AI agents do not get better by remembering everything. If every conversation, temporary state, and project detail is pushed into long-term memory, useful facts are buried under stale and irrelevant context. Memory without selection is noise.
Keepygaga keeps only a small set of durable facts that remain useful across tasks: who the user is, how they want an Agent to work, and a few ongoing topics, projects, responsibilities, or relationships. Temporary state stays in the current conversation or its direct source, such as a calendar, task manager, project documentation, issue tracker, or Git history. A fact enters core memory only when it has been deliberately judged useful across tasks.
That carefully selected core memory belongs to the user and follows them across Codex, Claude Code, WorkBuddy, Grok, Hermes, and Antigravity CLI instead of being trapped in separate host silos. Its source of truth is readable Markdown in one private Memory Root, preferably inside an Obsidian vault; any Markdown editor remains compatible.
The product has three deliberately separate surfaces:
Obsidian or another Markdown editor is where people inspect, correct, and organize memory.
MCP, Hooks, and the Agent Contract let agents read and update that memory under explicit constraints.
The
keepygagaCLI is a thin installation and operations control plane for host wiring, status, diagnostics, repair, upgrades, and uninstall. It is not a daily memory browser or editor.
Keepygaga ships the complete runtime: an eight-tool MCP server, a concise global Agent Contract, built-in cross-host Hooks, and the CLI control plane. It does not require a database, embeddings, a source checkout, or an external Hook runtime. Obsidian is the recommended human interface, not a runtime dependency.
Core memory contains profile.md, preferences.md, and direct pages below topics/, areas/, and people/. Ongoing projects share the optional canonical index areas/projects.md, created with its first project Fact: one Fact per project holds a brief, its canonical Authority, and its latest verified integrated outcome and release status when available, with later changes replacing that Fact and no major-milestone threshold. For Git projects, verify the canonical remote primary branch; record a published version only when a published Release points to a tag commit containing that outcome. Complete history, terminology, architecture, operating guides, decisions, and current state remain in the repository or another direct project source.
Host-native memories can continue to own host-specific conversation recall and project learning. Keepygaga owns the small set of stable user facts that should follow the user across hosts. A durable instruction admitted to source selection has exactly two possible owners: preferences.md when every connected Agent should follow it, or one host's effective global-rules entry when only that Agent should. Prose style and code style do not determine ownership by themselves. When the user has not specified the intended scope, the Agent must ask first, and one meaning may have only one source. Project rules stay in the project Authority and do not enter this choice.
The public MCP surface is exactly list, read, create, add, update, move, rename, and delete.
Session bootstrap injects only profile.md, preferences.md, a shared routing rule, and descriptions of the three dynamic scopes. Agents treat those descriptions as first-stage semantic routes: when a task depends on covered information that the current request or a live direct source does not already provide, they call list for that scope and select pages from the returned path, description, and aliases before reading them. New or semantically updated Facts receive a Store-owned local date suffix; existing undated Facts remain readable and upgrades do not rewrite the Memory Root.
Contract 3 users with existing project pages should follow the project-index migration before their next project-memory write under the current Agent Contract.
Install
Requirements: Python 3.12+ and uv.
Agent-guided installation (recommended)
Give the Agent host you are currently using this one sentence:
Quickly install or update Keepygaga for the Agent you are running in now from the latest official Release at https://github.com/TimWongUp/keepygaga: automatically choose install, update, current-host repair, or no action; preserve existing configuration and memory; ask me only for first-time initialization, a conflict, or a possible overwrite; then report the result and any restart requirement.
The Agent Fast Install To-do is the authoritative procedure for this path. It checks the installed version before downloading, limits work to the selected lifecycle branch and current Agent, and reuses existing data. The heavier Home Page source migration is loaded only for first initialization or a concrete duplicate. Host-native memory remains unchanged; when requested, the Agent supplies current official host documentation for user-managed configuration.
Manual installation
Download the keepygaga-X.Y.Z-py3-none-any.whl asset and SHA256SUMS from the same latest GitHub Release to private, non-symlinked paths. Immediately before installation, verify the exact wheel's SHA-256 entry and execute that same absolute path, replacing X.Y.Z below with the release version:
uv tool install /absolute/private/path/keepygaga-X.Y.Z-py3-none-any.whl
uv tool update-shellRestart the terminal so the tool directory is on PATH, then run keepygaga install.
The checksum detects corruption or an asset mismatch. It is not a signature, provenance proof, independent publisher authentication, or verification of dependencies resolved from the package index.
Interactive installation first offers a Memory Root path, then detects available hosts without selecting them on the user's behalf. Point it at an existing agents-memory tree to connect another Agent to the same memory. Once configured, later installs reuse that root automatically. --yes disables prompts even in a TTY, reuses the configured Memory Root or the platform default, and requires explicit target hosts:
keepygaga install --yes --host codex --host claude-codeSupported adapters are Codex, Claude Code, WorkBuddy, Grok, Hermes, and Antigravity CLI. Each adapter manages only its keepygaga MCP registration, the Keepygaga-owned Agent Contract block, and Keepygaga-owned Hook entries. Unrelated host configuration is preserved.
The default configuration and memory paths are platform-native. To reuse an existing private memory tree non-interactively, pass --memory-root during the first install. Do not place the memory tree in a public or automatically published directory.
New installations include five optional memory-capacity settings with the current defaults and adjustment notes. Existing configuration files are never rewritten. Edit the live config.toml; the next MCP call reloads these Store-only limits without requiring a schema refresh:
[memory.limits]
# Raise for richer profile/preferences; lower to reduce baseline context.
fixed_page_chars = 2000
# Raise for fewer, larger routed pages; lower to encourage earlier splitting.
dynamic_page_chars = 5000
# Raise to allow more topic pages; lowering never deletes existing pages.
topics_pages = 50
# Raise to allow more area pages; lowering never deletes existing pages.
areas_pages = 50
# Raise to allow more people pages; lowering never deletes existing pages.
people_pages = 100Every value must be a positive integer. Lower limits report existing excess through Doctor and constrain later growth; they do not delete or rewrite memory. The bounded repair input is derived as twice dynamic_page_chars.
Related MCP server: aurum-recall
Operate
keepygaga status
keepygaga status --latest-version vX.Y.Z --host codex
keepygaga repair --yes
keepygaga doctor --json
keepygaga uninstall --yesstatus treats the install-state file as discovery data only and reports when live host verification is still required. With the latest official release tag and current host, it returns a read-only lifecycle action: update, initialize, activate, repair, no_op, or manual_review. A missing launcher is the separate clean-install case. repair reconciles recorded hosts from their current configuration. uninstall removes only Keepygaga host wiring; it preserves the configuration and memory tree.
For a current-host-only update, download the newer wheel and matching SHA256SUMS, rehash the exact absolute wheel path, set UV_TOOL_DIR to the lifecycle.tool_root returned by planned status for that command, run uv tool install --force /absolute/private/path/keepygaga-X.Y.Z-py3-none-any.whl, then run keepygaga install --yes --host HOST. All hosts share the replaced runtime, so install also removes Keepygaga Hook commands for retired actions from every other recorded host (sibling_hooks). It adds nothing, so Hooks you removed stay removed, and it leaves their other Hooks, MCP registrations, and rules unchanged. Hosts whose full reconciliation is still behind are listed as stale_hosts; report them, and run keepygaga repair --yes when you intend to reconcile every recorded host.
keepygaga upgrade returns manual_review without changing anything: uv tool upgrade cannot discover a newer versioned Release wheel. Live installation metadata distinguishes the package manager from its source; locally downloaded archives require origin verification before runtime replacement because their metadata does not retain the official download URL. Same-version initialization and host reconciliation remain available without replacing the runtime.
Claude Code lifecycle commands honor CLAUDE_CONFIG_DIR; keep that environment variable set for install, status, repair, and uninstall.
Advanced deterministic host commands remain available as keepygaga host setup|uninstall HOST.
How integration works
keepygaga-mcpis the stable MCP launcher used by host registrations.The short managed Agent Contract contains only durable safety and routing rules.
The full read, convergence, mutation, conflict, and receipt protocol is delivered through negotiated MCP server instructions (modern discovery or the legacy initialize handshake).
Built-in Context Bootstrap and stateless Memory Route reminders are projected through each host's supported native events. Routing reminders include completion checks; there is no PostToolUse closeout Hook. Unsupported surfaces use documented fallbacks; Grok uses the managed Agent Contract for memory guidance.
Application, Agent Contract, Hook protocol, installer state, and memory schema versions evolve independently.
Configuration-level tests prove projection, preservation, idempotency, and failure boundaries. A host is live-verified only after its real client or official diagnostic confirms the keepygaga registration and all eight tools.
Development
uv sync
uv run pytest -q
uv run ruff check .
uv run pyright
uv run python scripts/smoke_mcp_server.py
uv build
uv run python scripts/check_distribution.py dist/*The keepygaga-knowledge sibling project is separate and is neither packaged nor imported by Keepygaga. See Architecture, Operations, and Contributing.
Acknowledgements
Keepygaga's core memory design was inspired by Claude Code's memory system.
Thanks also to the Claude Code team for their pioneering work on AI memory.
Security and license
Memory files are trusted local input and may contain personal data. Keep the memory root private, review changes before committing them anywhere, and report vulnerabilities through GitHub private vulnerability reporting.
MIT licensed. See LICENSE.
Available Tools
8 toolsaddADestructive
Add independent Facts and optionally replace the page description using its latest Page Snapshot. Group Facts for one page in one operation. On applied, reuse returned Page Snapshots and receipts; do not verify with read or list.
Inputs: operations (required). Returns: object
createA
Create new dynamic pages after full-batch validation. On applied, reuse returned Page Snapshots and receipts; do not call read or list solely to verify success.
Inputs: operations (required). Returns: object
deleteADestructive
Delete exact Facts with an optional page description, or delete dynamic pages, only after explicit current-turn user authorization. On applied, reuse surviving Page Snapshots and receipts; do not verify with read or list.
Inputs: operations (required). Returns: object
listARead-onlyIdempotent
Return one complete live topics, areas, or people Route Catalog. No search, matching, pagination, Facts, or write versions.
Inputs: scope (required). Returns: object
moveADestructive
Move exact Facts and optionally replace source or existing-destination descriptions, or atomically create a bounded new destination. Preserve Fact dates and leave at least one source Fact. On applied, reuse returned Page Snapshots and receipts; do not verify with read or list.
Inputs: operations (required). Returns: object
readARead-onlyIdempotent
Use before mutation unless current Page Snapshots are already available. Read unique canonical paths together; returned files contain Facts, opaque write versions, and capacity signals.
Inputs: paths (required). Returns: object
renameADestructive
Rename dynamic pages using latest Page Snapshots, one operation per page. On applied, reuse returned Page Snapshots and receipts; do not verify with read or list.
Inputs: operations (required). Returns: object
updateADestructive
Replace an exact Fact with an optional page description, update page metadata alone, or mechanically repair a repairable page using its latest version. On applied, reuse returned Page Snapshots and receipts; do not verify with read or list.
Inputs: operations (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The tools are mostly distinct: list and read serve different read purposes, and create/add/update/move/delete each target specific fact or page operations. However, update, move, and delete each have secondary description-related behaviors, so an agent could occasionally hesitate between mutation tools without carefully reading the details.
All tool names are lowercase single-word imperative verbs: list, read, create, add, update, move, rename, delete. This is a highly consistent and predictable naming convention, with no mixed styles or vague generic names.
Eight tools is well within the ideal range for a content-management server covering facts and pages. Each tool occupies a distinct role in the read/create/update/delete lifecycle, and none feel redundant or excessive.
The surface covers core page and fact lifecycle operations well: read/list, create/add, update/move/rename, and delete. Minor gaps exist, such as no fact-level search or standalone fact listing, but agents can work around these by reading canonical page paths.
Maintenance
Related MCP Connectors
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Persistent memory, inline redaction, per-agent access, and code localization for AI agents.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to have persistent, self-managing memory with bi-temporal supersession, timely forgetting, and recall under a limited context window, using MCP protocol.MIT
- AlicenseAqualityDmaintenanceA memory system for AI agents that maintains a human-readable, typed Markdown knowledge base with an always-in-context index, enabling recall, correction, and trust decay through MCP.71Apache 2.0
- AlicenseAqualityBmaintenanceMarkdown-first long-term memory for AI coding agents, enabling hybrid search over local files via MCP tools.926Apache 2.0

artificial-memoryofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to persist, recall, expand, trace, and inspect durable memories with provenance through MCP tools.MIT