The Complete Production SOP: How to Deploy and Run Episodic & Semantic Agent Memory Vector Retrieval in Autonomous AI Agents
Step-by-step guide to installing and running Episodic & Semantic Agent Memory Vector Retrieval in Codex, Claude Code, Cursor, and Windsurf. Free SOP guide.
Technical Overview & Architectural Context
Autonomous coding agents inherently suffer from statelessness across sessions, leading to hallucinated architectural decisions, repeated styling deviations, and amnesia regarding past debugging discoveries. When tasked with complex iterative codebases, agents often re-introduce previously deprecated patterns or ignore developer preferences (e.g., using specific ORM methods, interface naming conventions, or cloud infrastructure constraints) because conversational context is truncated. The 'agent-memory-vector-retrieval' skill solves this by enforcing a deterministic standard operating procedure (SOP) for indexing and querying long-term episodic memories and semantic preferences. With strict workspace read/write boundaries (security score 98/100, zero unauthorized network calls or arbitrary shell execution), the agent performs deterministic similarity scoring over a locally maintained embedding index before generating code. It injects past architectural decisions directly into an isolated `<relevant_memories>` block, preventing context drift while strictly maintaining token budget bounds.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Skill Directory Mounting & SKILL.md Provisioning
Create the local skill manifest directory and inject verified procedural rules into the agent context root.
Autonomous agent runners (Claude Code, Cursor, Codex, Windsurf) parse skills from repository-relative or global user paths. To activate vector retrieval deterministically, place the `SKILL.md` inside `.agents/skills/agent-memory-vector-retrieval/` or your project root's active rules directory. The YAML frontmatter instructs the runtime engine to trigger vector indexing on semantic memory intents without requiring custom CLI flags.
mkdir -p .agents/skills/agent-memory-vector-retrieval && cat << 'EOF' > .agents/skills/agent-memory-vector-retrieval/SKILL.md
---
name: "agent-memory-vector-retrieval"
description: "Persist and retrieve long-term episodic memories and user preferences with vector embeddings."
metadata:
author: "MemGPT"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "retrieve agent memory"
- "save user preference memory"
- "index episodic memory"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Episodic & Semantic Agent Memory Vector Retrieval
Maintains long-term agent memory: indexing user preferences, past project decisions, and architectural rules in a vector store, performing similarity retrieval before answering new queries.
## When to Invoke
Invoke this skill whenever you need to:
- retrieve agent memory
- save user preference memory
- index episodic memory
## Execution SOP & Rules
1. Embed episodic memory statements using high-quality semantic embedding models.
2. Retrieve top-k relevant memories using cosine similarity against the incoming prompt.
3. Inject retrieved memories into the system context under a dedicated <relevant_memories> block.
4. Allow users to inspect, update, or purge stored memory records for privacy compliance.
## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.
EOF---
name: "agent-memory-vector-retrieval"
description: "Persist and retrieve long-term episodic memories and user preferences with vector embeddings."
metadata:
author: "MemGPT"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "retrieve agent memory"
- "save user preference memory"
- "index episodic memory"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---To save context tokens, configure your top-k parameter to k=3 by default with a cosine similarity threshold cut-off at >= 0.78. This prevents polluting the context window with weakly related historical decisions.
Notice that 'permissions.net_access' is false. Do not attempt to invoke external remote vector clouds (like Pinecone/Qdrant Cloud) without updating frontmatter permissions; keep the vector database localized inside the workspace (e.g., local sqlite-vec or `.agents/memory.json`).
Local Vector Memory Store Initialization
Initialize the workspace-scoped vector store file structure and persistence schema.
Because external network calls are restricted by default under the security score audit, the agent manages episodic vectors directly in a local repository store. We initialize a deterministic JSON-based vector store structure inside `.agents/memory/` where embeddings and metadata payloads are persisted.
mkdir -p .agents/memory && cat << 'EOF' > .agents/memory/store.json
{
"schema_version": "1.0.0",
"records": [
{
"id": "pref-001",
"category": "preference",
"content": "Always use Zod for runtime input validation and avoid using raw TypeScript `any` assertions.",
"created_at": "2026-03-30T00:00:00Z",
"embedding": [0.0124, -0.0431, 0.0892, 0.0031]
}
]
}
EOF{
"schema_version": "1.0.0",
"records": [
{
"id": "pref-001",
"category": "preference",
"content": "Always use Zod for runtime input validation and avoid using raw TypeScript `any` assertions.",
"created_at": "2026-03-30T00:00:00Z",
"embedding": [0.0124, -0.0431, 0.0892, 0.0031]
}
]
}Commit `.agents/memory/store.json` to your git repository if team-wide agent architectural alignment is desired, or add `.agents/memory/*.local.json` to `.gitignore` for developer-isolated personalization.
Avoid saving sensitive auth tokens, production connection strings, or personal identifying information (PII) into episodic memory records. The skill's verification checklist strictly forbids uncommitted secrets.
Intent Matching & Trigger Verification
Trigger deterministic retrieval and memory indexing using targeted natural language triggers.
Agent runtimes scan user prompts against the `triggers` array (`retrieve agent memory`, `save user preference memory`, `index episodic memory`). When prompt intent matches, the runner automatically executes the procedural SOP: calculating vector embeddings, running nearest-neighbor similarity against `.agents/memory/store.json`, and formatting matching entries into the current working conversation.
retrieve agent memory for: 'Database schema migration rules and ORM configuration preference'Prefix prompts with explicit triggers like 'retrieve agent memory' or 'save user preference memory' to bypass heuristic intent ambiguity and guarantee immediate skill dispatch.
If you use ambiguous terminology like 'remember this', the runtime might use transient session scratchpads instead of executing the vector persistence SOP in `SKILL.md`.
Context Injection & Deterministic Output Gate
Inject retrieved embeddings into the prompt context and self-verify syntax and formatting.
Once retrieved, the agent must inject memories inside a strictly delineated `<relevant_memories>` block before generating code. The agent then performs linting and type-checks to guarantee that the generated code aligns with both the codebase constraints and the retrieved episodic context.
git status && npm run lint<relevant_memories>
<memory id="pref-001" score="0.94">
Always use Zod for runtime input validation and avoid using raw TypeScript `any` assertions.
</memory>
</relevant_memories>Wrap injected memories in XML tags (`<relevant_memories>...<relevant_memories>`) to prevent the LLM from confusing historic preferences with new instruction overrides.
Always run the verification checklist. If an agent adds an invalid memory or corrupts `.agents/memory/store.json`, downstream agent runs will fail with JSON parsing errors.
Real-World Scenario: Cross-Session Architectural Preference Retrieval for API Route Generation
“retrieve agent memory: Generate a new REST endpoint for POST /api/v1/subscriptions following our preferred validation and error handling patterns.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent runtime is executing inside an ultra-restricted sandbox that prevents modifying files outside the immediate working directory or the skill has missing `fs_write: workspace` permissions.
chmod 755 .agents/memory && chmod 644 .agents/memory/store.json && verify SKILL.md frontmatter includes 'fs_write: "workspace"'Root Cause: A previous agent session suffered a context cutoff during an append operation, leaving malformed, truncated JSON in the memory vector store.
node -e "const fs=require('fs'); try { JSON.parse(fs.readFileSync('.agents/memory/store.json')); console.log('Valid'); } catch(e) { fs.writeFileSync('.agents/memory/store.json', JSON.stringify({ schema_version: '1.0.0', records: [] }, null, 2)); console.log('Reset store to empty valid schema.'); }"Frequently Asked Questions (Episodic & Semantic Agent Memory Vector Retrieval SOP)
Q:Can I use Episodic & Semantic Agent Memory Vector Retrieval across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Because it relies on workspace-relative storage (`.agents/memory/store.json`) and standard markdown triggers, Codex Desktop, Claude Code CLI, Cursor, and Windsurf can read and update the same vector memory store synchronously across sessions.
Q:How does Episodic & Semantic Agent Memory Vector Retrieval prevent context window overflow during long agent sessions?
The skill enforces top-k nearest-neighbor filtering (typically top 3 to 5 records) combined with a strict cosine similarity threshold (>= 0.78). Instead of dumping the entire history of past prompts into the system prompt, only the most relevant episodic records are injected into a compact `<relevant_memories>` context block.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It requires only standard workspace filesystem read and write permissions (`fs_read: true`, `fs_write: 'workspace'`) and operates with `shell_exec: false` and `net_access: false` by default, eliminating remote exfiltration risks.
Ready to equip your autonomous agent with Episodic & Semantic Agent Memory Vector Retrieval?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.