GoodMemory is an open-source agent memory orchestration harness and context management system developed by hjqcan. Designed to give AI agents persistent state across runs, it provides structured storage, retrieval mechanics, and security controls for agentic coding tools and workflows. In daily use, GoodMemory runs as a terminal-driven framework and Model Context Protocol (MCP) server that interfaces with agent platforms including Anthropic Claude, OpenAI Codex, and native Kimi configurations. It manages persistent state through database backends such as PostgreSQL, exposing storage-isolated, read-only recall tools to AI agents while generating localized configurations inside `.goodmemory/` directories. GoodMemory differentiates itself from typical agent harnesses by treating memory recall and plugin execution as security boundaries. It enforces read-only recall operations to prevent unauthorized storage tampering during tool runs, incorporates pinned plugin security scanning, and includes a web-based inspector console (`apps/inspector-web`) with an admin API for auditing memory state and context retrievals. The project is open source and available on GitHub, currently maintaining a v0.7.x release line with active development around plugin validation and research proof gates.
MCP Recall Tools — Exposes Model Context Protocol recall endpoints configured as read-only storage to prevent data corruption during agent retrieval. - Multi-Agent & Provider Support — Provides native integration and setup flows for Claude, OpenAI Codex, and Kimi. - Plugin Security Scanning — Includes automated scanning workflows for pinned plugins to detect vulnerabilities before execution. - Inspector Web Console — Delivers an administrative web UI and API for inspecting, auditing, and managing agent context and memory tables. - Interactive CLI Setup — Generates local configurations (such as .goodmemory/codex.json) with interactive prompts for database and provider setup. - Configurable Storage Backends — Supports structured relational persistence layers, including PostgreSQL, for long-term agent state retention.
Use cases
Use Case: Persistent Cross-Session Memory for MCP Agents Developers running MCP-compatible agent environments (such as Claude Desktop or CLI agent harnesses) can connect GoodMemory to persist code context, user preferences, and repository insights across multiple coding sessions without leaking write permissions to retrieval tools.
Use Case: Auditing Agent Context via the Inspector Console Engineers debugging agent decisions can launch the Inspector Web interface to visualize stored memories, check what contextual records were retrieved during an agent run, and manage administrative settings over an internal API.
Use Case: Secure Multi-Provider Integration in CLI Workflows Teams using diverse models like OpenAI Codex, Anthropic Claude, and Kimi can use GoodMemory's interactive CLI configuration to set up isolated credentials, database connection strings, and security-scanned plugins across workspaces.
Who it is for
GoodMemory is suited for software engineers and agent architects building or running terminal-based AI agents who need persistent memory via MCP without granting agents unrestricted database write access. It is not designed for end users seeking a simple out-of-the-box GUI chat tool without database or CLI configuration requirements.
Install guide
Installation Clone the repository and install dependencies using Bun or Node (standard installation based on project repository structure): bash git clone https://github.com/hjqcan/GoodMemory.git cd GoodMemory bun install
First Run Run the CLI setup utility to interactively configure your database connection (e.g., PostgreSQL URL) and model provider settings for Claude or Codex: bash # Initialize local configuration inside .goodmemory/ bun run cli init Configure your environment variables if using PostgreSQL storage: bash export DATABASE_URL="postgresql://user:password@localhost:5432/goodmemory"
Example Session Start the GoodMemory MCP server to expose read-only recall tools to your agent client: bash # Start the memory server bun run start # Alternatively, launch the inspector console to audit memories bun run --cwd apps/inspector-web dev
Beads — Beads (bd) is an open-source task coordination and state orchestration harness for AI coding agents developed by Gastown Hall. It…
Letta Code — Letta Code is an open-source terminal-based AI coding assistant developed by Letta (formerly MemGPT). Built on top of the Letta…
pi-mem — pi-mem is an open-source memory harness and persistent context manager developed by Jo Inc for the Pi CLI coding agent.…
Vestige — Vestige is an open-source agent harness and persistent memory infrastructure framework developed by samvallad33. Designed specifically for AI coding agents…
SWE-agent — SWE-agent is an open-source autonomous software engineering agent harness built and maintained by researchers from Princeton University and Stanford University.…
OpenHands — OpenHands (formerly OpenDevin) is an open-source autonomous AI software development agent and orchestration platform. It provides an extensible runtime environment…