agentmemory-zcode-plugin

Zcode plugin for agentmemory — unified agent memory across sessions, projects, and tools, via MCP and 12 lifecycle hooks.

Note on CI: This repository ships a .github/workflows/ci.yml that runs lint, secrets scan, and structure checks on every push. Whether it actually executes depends on whether your GitHub account has Actions minutes enabled — public repositories on free accounts without billing attached may have Actions disabled. The same checks are reproducible locally: ./scripts/probe-hook.sh exercises all 12 hooks against a live agentmemory server, and the secrets/structure checks are the same grep / node -e commands listed in the workflow file.

What is this

A drop-in plugin for the Zcode CLI that wires the agentmemory memory layer into every session automatically. Once installed, every tool call, prompt, session boundary, and commit is captured as an observation and stored in a local agentmemory server. The agent can then recall, recap, handoff, and remember across sessions — full continuity without manual logging.

This is the Zcode counterpart of the official agentmemory integrations for Claude Code, Codex CLI, OpenCode, Cursor, Windsurf, and 14+ other agents. It follows the same hook conventions so plugin behaviour is consistent across the ecosystem.

Features

• 12 lifecycle hooks covering every meaningful moment in a Zcode session (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart, SubagentStop, Notification, TaskCompleted, Stop, SessionEnd) plus a git post-commit hook for commit↔session linking.
• 16 invocable skills (recall, recap, handoff, remember, forget, session-history, commit-context, commit-history, plus the seven agentmemory-* reference skills) — see SKILLS.md.
• MCP server for full programmatic access to the memory toolset (memory_recall, memory_save, memory_lesson_save, memory_crystallize, memory_health, etc.).
• Zero-LLM capture by default — observations are recorded as raw data. LLM-driven compression (AGENTMEMORY_AUTO_COMPRESS) and context injection (AGENTMEMORY_INJECT_CONTEXT) are opt-in to keep token spend under control.
• Project-scoped memory — observations are tagged with the project name resolved from git rev-parse --show-toplevel, so memory never bleeds across unrelated repositories.
• Post-commit hook links every git commit to the active session, so commit-context and commit-history skills can trace code changes back to the conversation that produced them.

Quick start

# 1. Install the agentmemory server (local REST API + viewer)
npm install -g @agentmemory/cli
agentmemory serve   # listens on http://localhost:3111

# 2. Install the plugin into Zcode
zcode plugin install agentmemory-zcode-plugin

# 3. Verify capture is working
zcode plugin verify agentmemory-zcode-plugin

# 4. Restart Zcode and start a session
zcode

After the first tool call, open http://localhost:3113 to see observations landing in real time.

Installation

See INSTALL.md for the full step-by-step guide, including the manual probe that confirms each hook fires correctly before you trust it with a real session.

Manual MCP server configuration

If you prefer to wire up the MCP server by hand (or are not using the Zcode marketplace), add the following block to the mcp.servers section of ~/.zcode/cli/config.json:

{
  "agentmemory": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@agentmemory/mcp"
    ],
    "env": {
      "AGENTMEMORY_SECRET": "",
      "AGENTMEMORY_TOOLS": "all",
      "AGENTMEMORY_URL": "http://localhost:3111"
    }
  }
}

Notes:

• "type": "stdio" is the default transport in Zcode. If your config already uses the shorthand form (omitting type), that is equivalent — both formats work.
• "AGENTMEMORY_URL" should match the address of your local agentmemory serve process. If you run the server on a different host or port, update it here.
• "AGENTMEMORY_SECRET" should be left empty for unauthenticated local servers. For authenticated deployments, set it via environment variable instead of committing it to config.json.
• "AGENTMEMORY_TOOLS" can be set to a comma-separated subset to limit which MCP tools the agent sees (see docs/01-configuration.md).

After saving the config, restart Zcode. The agentmemory tools (memory_recall, memory_save, etc.) will become available to the agent on the next session.

Hooks

This plugin registers 12 lifecycle hooks via hooks/hooks.json. Each hook delegates to a single Node script in hooks/scripts/ through the hooks/run-hook dispatcher.

Event	Script	Fires when	Default behaviour
SessionStart	session-start.mjs	A new Zcode session starts, resumes, or clears	Registers the session with the agentmemory server and optionally injects prior context
UserPromptSubmit	prompt-submit.mjs	The user submits any message	Captures the prompt as an observation tagged with session ID
PreToolUse	pre-tool-use.mjs	Before Edit, Write, Read, Glob, or Grep	Records the intended tool call (intent before execution)
PostToolUse	post-tool-use.mjs	After any tool completes	Captures the tool output (truncated to 8 KB, with base64 image extraction)
PostToolUseFailure	post-tool-failure.mjs	When any tool call fails	Records the error so debugging history is preserved
PreCompact	pre-compact.mjs	Right before Zcode trims long-session context	Snapshots the session so context can be restored after compaction
SubagentStart	subagent-start.mjs	A subagent is dispatched	Links the subagent session to the parent session
SubagentStop	subagent-stop.mjs	A subagent finishes	Closes the subagent linkage
Notification	notification.mjs	A system notification fires	Captures the notification text for later review
TaskCompleted	task-completed.mjs	A todo task is marked complete	Marks the corresponding action done in memory
Stop	stop.mjs	Generation finishes in a session	Bookmarks the stop point
SessionEnd	session-end.mjs	A session is closed	Finalises the session record
post-commit (git)	post-commit.mjs	After git commit runs	Links commit SHA → session ID for commit-context lookup

All scripts are fire-and-forget with a 500 ms self-exit. They never block the Zcode runtime. Total overhead per tool call: ~3 ms.

See docs/02-events-reference.md for payload schemas and field-level documentation for every event.

Skills

The plugin ships 16 skills under skills/. They are loaded by Zcode and can be invoked either through slash commands (/recall, /remember) or by the agent automatically when the situation matches.

Skill	Purpose
agentmemory	Top-level guide to the memory layer
agentmemory-architecture	Internal architecture and data model
agentmemory-config	Configuration flags and environment variables
agentmemory-hooks	Hook reference (this README condensed)
agentmemory-mcp-tools	Reference for the 50+ MCP tools
agentmemory-rest-api	REST API reference
agentmemory-agents	Multi-agent coordination patterns
recall	Search memory by meaning or keywords
recap	Summarise recent work in a project
handoff	Resume a previous session
remember	Save a fact, decision, or lesson to memory
forget	Delete memories (with audit trail)
session-history	List and inspect past sessions
commit-context	Show the conversation behind a commit
commit-history	List commits tied to a session
write-agentmemory-skill	Author new skills backed by memory

Configuration

All configuration is environment-driven. Defaults are baked into the scripts; override with environment variables for non-standard deployments.

Variable	Default	Purpose
AGENTMEMORY_URL	http://localhost:3111	REST endpoint of the agentmemory server
AGENTMEMORY_SECRET	(empty)	Bearer token for authenticated deployments
AGENTMEMORY_PROJECT_NAME	(resolved from git)	Override the project name used for memory scoping
AGENTMEMORY_INJECT_CONTEXT	false	Inject prior session context into SessionStart
AGENTMEMORY_AUTO_COMPRESS	false	Run LLM-driven compression on observations
AGENTMEMORY_TOOLS	all	Tool subset exposed by the MCP server
AGENTMEMORY_SDK_CHILD	(unset)	Skip capture when the agentmemory SDK is writing directly
AGENTMEMORY_SESSION_ID	(from payload)	Override session ID, used by the git hook

See docs/01-configuration.md for the full reference.

Project structure

agentmemory-zcode-plugin/
├── README.md                  # this file
├── INSTALL.md                 # step-by-step installation guide
├── LICENSE                    # MIT
├── CONTRIBUTING.md            # how to contribute
├── SECURITY.md                # vulnerability disclosure policy
├── CHANGELOG.md               # release history
├── package.json               # npm metadata
├── .zcode-plugin/
│   └── plugin.json            # Zcode marketplace manifest
├── hooks/
│   ├── hooks.json             # 12 lifecycle event registrations
│   ├── run-hook               # bash dispatcher
│   ├── run-hook.cmd           # Windows dispatcher
│   └── scripts/               # one Node script per event
├── skills/                    # 16 SKILL.md files (8 invocable, 7 reference, 1 meta)
├── scripts/
│   └── probe-hook.sh          # manual probe for debugging capture
├── docs/
│   ├── 01-configuration.md
│   ├── 02-events-reference.md
│   ├── 03-skills.md
│   ├── 04-architecture.md
│   └── 05-troubleshooting.md
└── .github/
    ├── ISSUE_TEMPLATE/
    └── workflows/             # CI for hook script linting

How it works

The plugin follows the standard Zcode hook contract. Each lifecycle event declared in hooks/hooks.json invokes hooks/run-hook <event>, a tiny bash dispatcher that maps the event name to the corresponding Node script in hooks/scripts/. Each script reads a JSON payload from stdin, builds a normalised observation, and POSTs it to ${AGENTMEMORY_URL}/agentmemory/observe with a 3-second timeout. Failures are swallowed silently — capture must never block the agent.

Project name resolution walks up from the hook payload's cwd, runs git rev-parse --show-toplevel, and takes the basename. This keeps memory scoped per-repository without hard-coded paths.

The MCP server (@agentmemory/mcp) is launched by Zcode through the standard mcpServers block in .zcode-plugin/plugin.json and exposes the full programmatic memory toolset.

Full architecture deep-dive in docs/04-architecture.md.

Troubleshooting

Most capture failures come from one of four causes: the agentmemory server is not running, a hook script is missing the executable bit, an environment variable is unset, or two plugin layers are double-registering hooks.

See docs/05-troubleshooting.md for the diagnostic flowchart, the scripts/probe-hook.sh utility, and a recipe for verifying each hook fires exactly once.

Security

Observations are captured verbatim from tool input and output. You are responsible for what your tools touch. See SECURITY.md for the threat model, the secrets-redaction checklist, and how to report vulnerabilities.

Contributing

PRs welcome. Read CONTRIBUTING.md first — it covers the plugin layout, hook-script conventions, how to add a new skill, and the manual-probe checklist before opening a PR.

License

MIT © 2026 Maatq1544 and contributors.

This plugin is a Zcode integration of agentmemory by Rohit Ghumare. The hook scripts and skills here are derivative works of the upstream agentmemory plugin, which is distributed under the Apache License 2.0. See NOTICE for attribution details.