Description
BotCreds Agent Memory gives your AI agents a persistent, structured memory store accessible via WordPress REST API and MCP (Model Context Protocol).
Two modes of operation:
- KV Mode (default) — Simple key-value store with tags, expiry, and text search. No external dependencies. Works out of the box.
- Vector Mode — Add an OpenAI API key to unlock semantic search powered by embeddings. Entries are embedded in the background and searched by meaning alongside keyword matches. Pending embeddings remain searchable by exact text.
Conversation archive and sync (3.1):
Save explicitly selected original conversation text outside a chat tool, with resumable uploads, session records, artifact references and compaction checkpoints. Retrieve original passages and search archive text within an explicitly enrolled scope. The included reference client reads operator-reviewed JSONL files; it is not an automatic OpenClaw or Claude Code collector.
Manually delete a conversation and its managed archive/checkpoint/session/artifact records, with permanent deletion markers that prevent stale clients from re-uploading it. No automatic age-based forgetting is enabled. Independent curated KV memory, external files and backups are not deleted by archive deletion. In 3.2, managed derived memories tied to deleted sources are purged as described below.
Archive access is separate from shared-memory grants: a host administrator must explicitly enroll each scope/user, including administrators, using wp agent-memory archive-scope project/name USER_ID. Server sync operations require InnoDB tables. Checkpoints verify submitted archive ranges, not completeness of native client capture. No original conversations are captured or uploaded automatically.
Suggestions and evidence-backed memory (3.2):
Agent Memory → Suggestions provides original-source selection, optional WordPress AI Client/Connectors generation, an evidence-linked review inbox, immutable revisions, and explicit application of approved facts/decisions to current shared memory. Approval alone does not publish a memory. Generated Skill files are never installed or executed.
Archive scopes require explicit host enrollment, separate from curated-memory grants, including for administrators. Native generation requires compatible WordPress AI Client/Connectors APIs and a configured provider; basic storage/search and external proposal clients do not. Applying a suggestion publishes into the shared curated store, whose readers may differ from archive participants. Source deletion also purges managed derived memory. Automatic conversation capture is not included.
Key features:
- REST API with full CRUD (create, read, update, delete)
- MCP endpoint for AI agent tool integration
- Namespace-based access control per WordPress user
- Automatic embedding generation via WP-Cron
- Bulk backfill for existing entries
- Expiry support for temporary memories
- Tag-based filtering and organization
- WordPress Application Password authentication
Built for AI agents, by AI agents.
Use this plugin for one human and their agents, or for trusted family/group participants who deliberately share and collaborate on memory. It is not a private-vault hosting service for mutually untrusted users. Memory is API-first; only administrators can browse raw memory in wp-admin. Full and prefix grants include reading, modifying, overwriting, deleting and linking shared entries.
Codex Integration
BotCreds Agent Memory ships official tool adapters for OpenAI Codex in assets/codex/.
Quick start:
- Set env vars:
BOTCREDS_MEMORY_URL(your WP site) andBOTCREDS_MEMORY_KEY(username:app_password) - Copy
assets/codex/AGENTS.mdcontent into your project’sAGENTS.md - Import tools in your Codex task:
import tools from './assets/codex/memory-tools.js'(JS) or addmemory-tools.pyto your repo
Full docs: https://botcreds.com/agent-memory/
External services
This plugin optionally connects to the OpenAI API to generate vector embeddings for semantic search.
- Service: OpenAI Embeddings API (
https://api.openai.com/v1/embeddings) - When it is used: Only when an OpenAI API key is configured in the plugin settings. Without a key, the plugin operates in KV-only mode and makes no external requests.
- What is sent: The text content of memory entries you explicitly write or update.
- OpenAI Terms of Use: https://openai.com/policies/terms-of-use
- OpenAI Privacy Policy: https://openai.com/policies/privacy-policy
Installation
- Upload the
botcreds-agent-memoryfolder to/wp-content/plugins/. - Activate the plugin through the Plugins menu in WordPress.
- (Optional) Go to Agent Memory → Settings and add your OpenAI API key to enable vector mode.
- As an administrator, open Users → Edit User → Agent Memory Access for each nonadmin participant and explicitly choose Full shared-store API access or API access to listed prefixes only. Unconfigured users have no memory access. Administrators remain unrestricted.
- Create a WordPress Application Password for the authorized participant account under Users → Profile → Application Passwords. Use a dedicated nonadmin account for an agent that does not need administrator rights.
- Use the REST API at
/wp-json/botcreds-memory/v1/with Basic Auth.
FAQ
Do I need an OpenAI API key?
No. Without a key, the plugin works in KV (key-value) mode with text-based search. An OpenAI key enables semantic vector search via embeddings.
How does authentication work?
The plugin uses WordPress authentication, including Application Passwords with HTTP Basic Auth. Authentication alone does not grant memory access: nonadmins also need an explicit full-store or prefix grant from an administrator. All credentials for a WordPress account share that account’s memory grant. A person holding an agent credential can make the same API calls; agent-only is an intended workflow, not proof of software identity.
Can I restrict which keys a user can access?
Yes. Go to Users → Edit User → Agent Memory Access, select API access to listed prefixes only, and enter literal, case-sensitive prefixes such as family/. An empty prefix list grants no access; full-store access must be explicitly selected. An explicit No memory access selection overrides retained prefix settings. Existing nonempty prefix grants from earlier versions remain scoped, but previously blank/unconfigured nonadmin accounts are now denied until an administrator grants access. Administrator accounts remain unrestricted.
What is MCP?
MCP (Model Context Protocol) is a standard for AI agents to discover and use tools. The plugin exposes an authenticated MCP manifest (GET) and JSON-RPC tool calls (POST) at /wp-json/botcreds-memory/v1/mcp.
How are embeddings generated?
When you save an entry and an OpenAI key is configured, the plugin schedules a WP-Cron event to generate the embedding asynchronously. Existing entries can be backfilled from the Settings page.
What embedding model is used?
By default, text-embedding-3-small (1536 dimensions). You can change this in the Settings page.
Changelog
3.2.0
- Add an evidence-linked Suggestions inbox with original-source inspection, approval, dismissal and immutable revisions.
- Add optional native processing previews using configured WordPress AI Client/Connectors providers, with explicit export/cost consent and no automatic saving.
- Apply approved facts/decisions explicitly to managed shared-store memory with safe replacements and idempotent application receipts.
- Purge managed derived memory and matching revision snapshots when their original source is deleted. Never restore superseded decisions automatically.
- Include cumulative 3.1 archive, session, artifact, checkpoint and deletion-aware sync foundations. Automatic OpenClaw/Claude Code capture is not included.
- Retain external processor support and basic storage/search without an AI provider. Generated Skill files are not installed or executed.
3.1.0
- Add exact-scope conversation archives, immutable original messages, resumable sync receipts and a deletion-aware SQLite reference client.
- Add revision-safe session records, compaction checkpoint verification and immutable artifact references.
- Retrieve hash-verified original passages and same-session context; search original text within enrolled scopes.
- Support explicit same-conversation corrections and checkpoint-linked session summaries without treating newer claims as automatic truth.
- Manually delete conversations or retire scopes, with transactional derivative purge and permanent no-resurrection markers.
- Include an incremental operator-reviewed JSONL adapter. No automatic OpenClaw/Claude Code capture, age expiry or AI memory processing is included.
3.0.4
- Require explicit memory API authorization for nonadmins; ordinary authenticated WordPress accounts no longer gain full access by default.
- Add administrator-managed No access, Full shared-store API access and Listed prefixes controls to user profiles.
- Preserve existing nonempty prefix grants without widening access; blank/unconfigured nonadmins now require an explicit grant.
- Enforce grants at REST/MCP route gates, tool dispatch, per-key checks and metadata filtering.
- Explicitly guard memory admin page callbacks and document trusted shared-store behavior, account-level credentials and upgrade impact.
3.0.3
- Scope namespace/tag labels and counts to entries accessible to the current user, on MCP and REST.
- Hide backfill tools from nonadministrator discovery; direct-call permission checks remain enforced.
- Explain literal case-sensitive prefixes (no wildcard support) in profile help.
- Add total_attempts, max_attempts_per_entry and attempts_scope status fields; preserve legacy fields.
- Add optional min_similarity to MCP/REST search. Applies only to semantic matches; text hits remain.
- Document full client relaunch after upgrades when a client caches tool discovery.
3.0.2
- Add admin-only embedding_backfill_status and embedding_backfill_control MCP tools.
- Add embedding backfill REST status/control, WP-CLI commands and admin manual batch/retry controls.
- Replace cursor skipping with durable content-aware retry jobs, exponential backoff, bounded attempts and worker leases.
- Pause on authentication failures, expose sanitized diagnostics and prevent stale embeddings after concurrent edits.
- Reserve attempts and schedule recovery before network requests; recover interrupted work without overwriting existing vectors.
3.0.1
- Fix false save failures and wrong embedding targets caused by revision insert IDs.
- Wire relationship MCP tools and enforce access to both relationship endpoints.
- Default entry attribution to the authenticated user when omitted.
- Avoid duplicate content revisions and preserve embeddings on no-change saves.
- Include keyword matches alongside semantic search so pending embeddings do not hide exact text.
3.0.0
- New: Entry relationships — create typed links between entries (references, parent, see-also, supersedes)
- New: REST endpoints for relationship CRUD: POST/GET/DELETE /entries/{key}/relationships
- New: MCP tools: memory_link, memory_links, memory_unlink
- New: Relationship stats endpoint: GET /relationships/stats
- New: Settings page Relationships tab with counts and recent relationships
- Updated: Plugin description to reflect multi-harness support
- Updated: Version bump to 3.0.0
2.4.0
- Added Codex integration — tool adapters and AGENTS.md snippet in assets/codex/
2.3.0
- Added: Revision history — every write creates a revision with author attribution
- Added:
GET /entries/revisions?key=REST endpoint — full audit trail per entry - Added: MCP tool
get_revisions(key)— ask who changed what and when - Added: Author capture on all writes (WP user id + display name)
2.2.0
- Added: Namespaces — keys support
/-delimited paths (e.g.project/clawpress/brief), auto-indexed - Added:
GET /namespacesREST endpoint — browse namespace tree with entry counts - Added:
GET /tagsREST endpoint — list all tags with counts - Added:
?namespace=and?tag=filter params onGET /entries - Added: MCP tools
get_by_tag,list_namespaces,list_tags - Added:
namespaceandtagparams onlist_memoryandsearch_memoryMCP tools - Improved: tag filtering now supports
?tag=query param (single tag) alongside existing?tags=(CSV)
2.1.0
- Change: Site hardening is now disabled by default. It was previously enabled by default, which could block front-end traffic on existing sites.
- Add: Hardening toggle added to Agent Memory > Settings > Site Hardening with clear warning label.
- Add:
botcreds_memory_hardenedoption registered via Settings API (sanitized, integer, default 0).
2.0.10
- Fix: Remove invalid
botcredscontributor (not a WordPress.org username). - Fix: Add Plugin URI and License URI to plugin header to match BotCreds branding standards.
- Fix: Align tags to hyphenated format and lower Requires at least to 5.6.
2.0.9
- Fix: Replace non-standard bcam prefix with botcreds_memory in admin page slug, hook names, nonce actions, and POST key names for WordPress.org review compliance.
2.0.8
- Fix fatal error on settings pages: guard Settings API registration with is_admin() check.
2.0.7
- Fix PHP 7.4 compatibility: replace str_starts_with() with strpos()-based equivalent.
2.0.6
- Register plugin settings on rest_api_init so show_in_rest works correctly.
- Expose OpenAI key and embedding model settings via the REST API.
2.0.4
- Security hardening: return 403 for unauthenticated HTML requests to the frontend.
2.0.3
- MCP: implement proper JSON-RPC 2.0 protocol for tool calls and responses.
2.0.2
- Update plugin author to Joe Boydston.
- Add jboydston as WordPress.org contributor.
2.0.1
- Fix Plugin Check errors: SQL preparation phpcs:ignore annotations, nonce verification in user profile save, i18n ordered placeholders, error_log wrapped in WP_DEBUG guard.
- Update tested up to WordPress 7.0.
2.0.0
- Initial public release.
- KV mode: key-value store with tags, expiry, and text search.
- Vector mode: semantic search via OpenAI embeddings.
- REST API: full CRUD under
/wp-json/botcreds-memory/v1/. - MCP endpoint: manifest and tool call handler.
- Access control: per-user namespace restrictions.
- Admin UI: entries browser, settings page, access control overview.
- WP-Cron: automatic embedding generation and bulk backfill.
