wp-agentic-writer/docs/implementation/MEMANTO_INTEGRATION_PLAN.md

MEMANTO Integration Plan — Optional Context Enhancement

Version: 1.0 Date: 2026-06-07 Status: Planning Depends on: MEMANTO_PRICING_STRATEGY.md

---

Design Principles

1. MEMANTO is optional. The plugin's built-in Context Builder (class-context-builder.php) remains the default and always works without MEMANTO.
2. MEMANTO enhances, never replaces. MySQL sessions (wpaw_conversations) remain the primary session store. MEMANTO runs parallel.
3. Zero disruption on failure. If MEMANTO is unreachable, the plugin falls back to existing behavior with no error shown to the user.
4. Server-side only. All MEMANTO API calls happen in PHP. The frontend (sidebar.js) is unaware of MEMANTO — it just sees richer or leaner context in AI responses.
5. User brings own Moorcheh key. Plugin stores MEMANTO URL + Moorcheh API key in WordPress settings. Never hardcoded.

---

Architecture Overview

                         ┌────────────────────────────────────────────────┐
                         │              WordPress Backend                  │
                         │                                                 │
  User Message ──────►  │  Gutenberg Sidebar (handle_chat_request)        │
                         │       │                                         │
                         │       ▼                                         │
                         │  Context Builder (build_system_message)         │
                         │       │                                         │
                         │       ├──► MySQL Session (wpaw_conversations)  │
                         │       │         primary store                   │
                         │       │                                         │
                         │       ├──► Memanto Client ──► MEMANTO API      │
                         │       │         (if configured)                 │
                         │       │            │                            │
                         │       │            ├── recall (retrieve)        │
                         │       │            └── remember (store)        │
                         │       │                                         │
                         │       ▼                                         │
                         │  Merged Context → AI Provider → Response        │
                         └────────────────────────────────────────────────┘

Data Flow: Two Paths

Path	When	What Happens
Default (no MEMANTO)	MEMANTO URL not configured in settings	Context Builder uses MySQL session only. Identical to current behavior.
MEMANTO active	MEMANTO URL + Moorcheh key configured and validated	Context Builder queries MEMANTO for relevant memories before building context. After AI response, significant events are stored in MEMANTO.

---

Agent Design

Agent Naming Convention

Agent ID	Scope	Purpose
wp-user-{wordpress_user_id}	Per WordPress user	Cross-post preferences: writing style, tone, audience, language, brand voice
wp-post-{wordpress_post_id}	Per post	Article-specific: plan decisions, rejections, research, section progress

Memory Types Used

MEMANTO Type	When Stored	Example
preference	User sets/changes post config	"User prefers conversational tone, intermediate audience"
instruction	User sends chat message	"Focus on plugin vulnerabilities only"
decision	User approves/rejects plan	"Approved 5-section outline for WordPress security"
artifact	Plan generated, section written	"Plan: 5 sections covering X, Y, Z"
context	Session ends / summarize	"Article at 60% completion, 3 of 5 sections done"
error	User corrects AI output	"User rejected generic tips approach, wants specific plugin recommendations"

Tags Convention

Tags enable targeted recall. Every memory includes:

Tag	Example	Purpose
post:{id}	post:42	Scope recall to specific post
site:{domain}	site:example.com	Scope to WordPress site
mode:{mode}	mode:planning	What mode was active
model:{model}	model:deepseek-chat	Which model was used

---

New Files to Create

includes/class-memanto-client.php

PHP client for MEMANTO API v2. Singleton class.

Public Methods:

Method	Description
is_configured()	Returns true if MEMANTO URL + Moorcheh key are set in settings
is_healthy()	Calls /health endpoint, caches result for 5 minutes
ensure_agent( $agent_id )	Creates agent via POST /api/v2/agents if not exists
activate_session( $agent_id )	POST /api/v2/agents/{id}/activate, caches session token in transient
remember( $agent_id, $content, $type, $tags, $title )	POST /api/v2/agents/{id}/remember
batch_remember( $agent_id, $memories )	POST /api/v2/agents/{id}/batch-remember
recall( $agent_id, $query, $type, $limit )	POST /api/v2/agents/{id}/recall
recall_recent( $agent_id, $limit )	POST /api/v2/agents/{id}/recall/recent
deactivate_session( $agent_id )	POST /api/v2/agents/{id}/deactivate

Internal Mechanics:

• Session token stored in WP transient: wpaw_memanto_token_{agent_id} (6-hour TTL matching MEMANTO JWT)
• Auto-reactivates on expired token (catches 401, re-activates, retries)
• All calls use wp_remote_post / wp_remote_get with 10-second timeout
• All calls wrapped in try/catch with wpaw_debug_log on failure
• Moorcheh API key passed via X-API-Key header or configured in MEMANTO instance (depending on MEMANTO's auth model)

includes/class-memanto-context-enhancer.php

Orchestrates when and what to remember/recall. Hooks into existing Context Service.

Public Methods:

Method	Hook Point	Description
on_session_start( $session_id, $post_id, $user_id )	Session creation	Ensures user + post agents exist; recalls previous session state
on_user_message( $session_id, $content, $post_id )	After user sends message	Stores instruction-type memory
on_plan_generated( $post_id, $plan )	After plan creation	Stores artifact-type memory
on_plan_approved( $post_id, $plan )	User approves plan	Stores decision-type memory
on_plan_rejected( $post_id, $reason )	User rejects/requests changes	Stores error-type memory with rejection reason
on_section_written( $post_id, $section_id, $summary )	After section generation	Stores artifact-type memory
on_block_refined( $post_id, $block_id, $instruction )	After refinement	Stores instruction-type memory
on_config_saved( $post_id, $config )	Post config updated	Stores preference-type memory to both user and post agents
on_session_end( $session_id, $post_id )	Session completed/archived	Summarizes session, stores context-type memory, deactivates session
recall_for_context( $post_id, $user_id, $current_message )	Before building context	Returns recalled memories to enrich prompt

Recall Strategy (recall_for_context):

1. Recall recent memories from post agent (limit: 10)
2. Recall semantically relevant memories from post agent (query: user's current message, limit: 5)
3. Recall user preferences from user agent (query: "writing preferences tone audience", limit: 5)
4. Deduplicate by content hash
5. Return structured array of recalled items

---

Files to Modify

includes/class-settings-v2.php

Add MEMANTO configuration section:

MEMANTO Context Keeper
├── Enable MEMANTO integration (checkbox, default: off)
├── MEMANTO Instance URL (text, e.g., https://abc123.context.wpagentic.dev)
├── Moorcheh API Key (password, user's own key)
└── Connection Status (read-only, shows "Connected" / "Not configured" / "Error: ...")

Add a "Test Connection" button that calls MEMANTO /health endpoint.

includes/class-context-builder.php

Modify build_for_task() method. After line ~52 where $saved_context is loaded:

// Existing: MySQL context
$saved_context = $context_service->get_context( $session_id, $post_id );

// NEW: MEMANTO enhancement (if configured)
$memanto_context = array();
$memanto_client = WP_Agentic_Writer_Memanto_Client::get_instance();
if ( $memanto_client->is_configured() && $memanto_client->is_healthy() ) {
    $enhancer = WP_Agentic_Writer_Memanto_Context_Enhancer::get_instance();
    $memanto_context = $enhancer->recall_for_context(
        $post_id,
        get_current_user_id(),
        $request_params['latestUserMessage'] ?? ''
    );
}

Modify build_working_context() to include a new section:

// After existing sections, before "Recent saved conversation excerpts"
if ( ! empty( $memanto_context ) ) {
    $memory_lines = $this->format_memanto_memories( $memanto_context );
    if ( '' !== $memory_lines ) {
        $sections[] = "PERSISTENT MEMORY (recalled from MEMANTO):\n" . $memory_lines;
    }
}

Key rule: MEMANTO context is additive. It never replaces the existing BACKEND CONTINUITY CONTEXT section. It supplements it.

includes/class-context-service.php

Add MEMANTO write-through hooks in key methods:

Method	Hook Added
save_plan()	$enhancer->on_plan_generated( $post_id, $plan )
update_session_context()	$enhancer->on_config_saved() if config changed
add_message()	$enhancer->on_user_message() for user-role messages
clear_context()	Optionally clear MEMANTO post agent memories

includes/class-gutenberg-sidebar.php

Add MEMANTO hooks in key handler methods:

Handler	Hook Added
handle_chat_request()	$enhancer->on_user_message() after saving to MySQL
handle_generate_plan()	$enhancer->on_plan_generated() after successful plan
handle_execute_article()	$enhancer->on_section_written() per section
handle_refine_block()	$enhancer->on_block_refined()
handle_summarize_context()	Skip AI call if MEMANTO active — return cached recall instead
handle_detect_intent()	Skip AI call if MEMANTO active — use regex + MEMANTO context instead

Add new REST endpoint:

POST /wp-agentic-writer/v1/memanto/status
→ Returns: { connected: bool, agent_count: int, memory_count: int, last_recall: string }

includes/class-autoloader.php

Register the two new classes:

• class-memanto-client.php → WP_Agentic_Writer_Memanto_Client
• class-memanto-context-enhancer.php → WP_Agentic_Writer_Memanto_Context_Enhancer

assets/js/sidebar.js (minimal change)

No MEMANTO-specific logic needed. Optional enhancement:

• Show a small "🧠 Memory active" indicator when MEMANTO is connected
• Show "memories recalled: N" in the context audit display

---

Graceful Degradation Strategy

MEMANTO call succeeds?
├── YES → Merge MEMANTO context into working context
└── NO
    ├── MEMANTO not configured → Use MySQL-only context (default behavior)
    ├── MEMANTO timeout (>10s) → Log warning, use MySQL-only context
    ├── MEMANTO 401 (token expired) → Re-activate session, retry once, then fallback
    └── MEMANTO 5xx (server error) → Log error, use MySQL-only context

User never sees an error from MEMANTO. The worst case is they get the same experience as users without MEMANTO.

---

Implementation Phases

Phase 1: Core Client (Week 1)

Goal: MEMANTO client class + settings UI + connection validation

Task	File	Details
Create Memanto Client	class-memanto-client.php	All API methods, session token management, error handling
Create Context Enhancer shell	class-memanto-context-enhancer.php	Skeleton with is_configured() check on every method
Add settings section	class-settings-v2.php	URL field, API key field, enable checkbox, test button
Register in autoloader	class-autoloader.php	Add both new classes
Add REST status endpoint	class-gutenberg-sidebar.php	/memanto/status endpoint

Validation: Admin can configure MEMANTO URL + Moorcheh key, test connection, see "Connected" status. No functional changes to AI features yet.

Phase 2: Write-Through Memory (Week 2)

Goal: Store memories on every meaningful action

Task	Hook Point	Memory Type
Store on user message	handle_chat_request()	instruction
Store on plan generated	handle_generate_plan()	artifact
Store on plan approved	After plan save in frontend	decision
Store on plan rejected	Plan revision flow	error
Store on section written	handle_execute_article()	artifact
Store on block refined	handle_refine_block()	instruction
Store on config saved	update_session_context()	preference
Store on session end	Session completed/archived	context

Validation: Write an article with MEMANTO enabled. Check MEMANTO API (via recall endpoint) that memories were stored. Verify plugin still works perfectly with MEMANTO disabled.

Phase 3: Context Enrichment (Week 3)

Goal: Recall memories to enrich AI prompts

Task	File	Details
Add recall_for_context()	class-memanto-context-enhancer.php	3-recall strategy (recent, semantic, preferences)
Modify build_for_task()	class-context-builder.php	Merge recalled memories into working context
Add format_memanto_memories()	class-context-builder.php	Format recalled items as compact prompt text
Skip summarize-context when MEMANTO active	class-gutenberg-sidebar.php	Return cached recall instead of AI call
Skip detect-intent when MEMANTO active	class-gutenberg-sidebar.php	Use regex + MEMANTO context instead

Validation: Write an article. Mid-session, close the browser. Reopen the post. Verify AI "remembers" context from recalled memories. Compare AI response quality with/without MEMANTO.

Phase 4: Cross-Session Restore (Week 4)

Goal: Seamless experience when returning to a post after days/weeks

Task	Details
Session restore on load	When post editor opens, recall recent post memories. Build a "restored session" system message.
Frontend indicator	Show "🧠 Restored from memory" badge in sidebar
User preference carry-over	On new post creation, recall user agent preferences for default post config
Session deactivation	On session end, call MEMANTO deactivate to trigger summary generation

Validation: Create an article. Complete 50%. Wait 1 day. Open the post again. Verify AI picks up where it left off without user re-explaining context.

Phase 5: Polish & Edge Cases (Week 5)

Task	Details
Memory pruning	On session end, summarize verbose raw messages into compact context memories
Connection health UI	Real-time status indicator in plugin sidebar header
Moorcheh limit warning	When approaching 10K vectors, show admin notice with upgrade link
Error logging	Detailed MEMANTO error logging with wpaw_debug_log
Settings validation	Validate URL format, API key format, connection test before saving

---

Testing Strategy

Unit Tests

Test	Description
test_memanto_client_not_configured	Client returns false when settings empty
test_memanto_client_health_check	Mock /health response, verify caching
test_memanto_client_remember	Mock remember API, verify payload structure
test_memanto_client_recall	Mock recall API, verify response parsing
test_memanto_client_session_lifecycle	Activate → remember → recall → deactivate
test_enhancer_graceful_fallback	MEMANTO returns error, context builder still works
test_context_builder_with_memanto	Verify MEMANTO context is included in working context
test_context_builder_without_memanto	Verify no MEMANTO content when not configured

Integration Tests

Test	Description
Full article with MEMANTO	Chat → Plan → Write → Refine. Verify memories stored at each step.
Full article without MEMANTO	Same flow. Verify no MEMANTO calls made. Plugin works identically.
MEMANTO goes down mid-session	Start with MEMANTO active. Simulate timeout. Verify graceful fallback.
Cross-session restore	Write 50% of article. Simulate new session. Verify AI context restored.
Multi-site with same MEMANTO	Use same MEMANTO instance across 2 sites. Verify agent isolation.

Manual Test Checklist

• Plugin activates with no MEMANTO settings — works normally
• MEMANTO URL set but Moorcheh key empty — shows "not configured"
• MEMANTO URL + invalid key — shows "connection error"
• MEMANTO URL + valid key — shows "connected"
• Write article with MEMANTO on — AI responses include recalled memory
• Write article with MEMANTO off — identical to current behavior
• Disable MEMANTO mid-session — no errors, fallback to MySQL-only
• Re-enable MEMANTO — picks up from where it left off
• Check MEMANTO recall endpoint — memories exist for test post

---

Performance Considerations

Concern	Mitigation
MEMANTO recall adds latency to every AI call	Cache recall results in transient (5-min TTL). Only recall when context builder runs.
Session token expires mid-request	Auto-reactivate on 401. Single retry.
Too many memories stored	Batch-remember to reduce HTTP calls. Summarize on session end.
MEMANTO instance overloaded	10-second timeout on all calls. Graceful fallback.
WordPress transient cache bloat	Use specific key patterns. Clean up on session end.

---

Settings UI Specification

MEMANTO Context Keeper Section

Located in WP Agentic Writer → Settings → MEMANTO tab.

┌─────────────────────────────────────────────────────────────────┐
│  MEMANTO Context Keeper                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ☑ Enable MEMANTO integration                                   │
│                                                                  │
│  MEMANTO Instance URL                                           │
│  ┌──────────────────────────────────────────────────┐          │
│  │ https://abc123.context.wpagentic.dev              │          │
│  └──────────────────────────────────────────────────┘          │
│                                                                  │
│  Moorcheh API Key                                               │
│  ┌──────────────────────────────────────────────────┐          │
│  │ ••••••••••••••••••••••••                          │          │
│  └──────────────────────────────────────────────────┘          │
│  ℹ️ Get a free API key at moorcheh.ai (10K vectors/month)      │
│                                                                  │
│  Connection Status: 🟢 Connected                                │
│  Last checked: 2 minutes ago                                     │
│                                                                  │
│  [Test Connection]                                               │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│  ℹ️ MEMANTO is an optional add-on that provides persistent      │
│     memory for your AI writing assistant. Your AI will remember │
│     context across sessions and posts. The plugin works         │
│     perfectly without MEMANTO.                                   │
│                                                                  │
│  Get MEMANTO at: wpagentic.dev/memanto                          │
└─────────────────────────────────────────────────────────────────┘

---

Summary

Aspect	Decision
Scope	Optional enhancement, not a dependency
New files	class-memanto-client.php, class-memanto-context-enhancer.php
Modified files	class-context-builder.php, class-context-service.php, class-gutenberg-sidebar.php, class-settings-v2.php, class-autoloader.php
Frontend changes	Minimal: status indicator only
Fallback behavior	Full graceful degradation to MySQL-only context
Implementation time	5 weeks (1 week per phase)
Testing priority	Phase 2 (write-through) and Phase 3 (recall) are critical paths

---

Document Date: June 7, 2026 Status: Draft — Ready for Phase 1 implementation