Kratos Memory System Usage Guide

Overview

Kratos is an ultra-lean memory system that provides project-isolated persistent memory for AI coding assistants. It uses SQLite with FTS5 for <10ms memory retrieval and automatically isolates memories per project.

When to use Kratos:

• Storing architectural decisions
• Remembering project-specific patterns
• Persisting configuration choices
• Tracking technical debt
• Recording incident learnings

Official Repository: https://github.com/ceorkm/kratos-mcp

---

Core Principles

1. Project Isolation

• Each project gets its own isolated memory database
• No cross-contamination between projects
• Auto-detected from working directory
• Memory hash derived from absolute path

2. Atomic Memory Storage

• Store facts, not essays
• One concept per memory
• Clear, searchable keywords
• Include context (dates, file paths)

3. Search-First Design

• Memories optimized for full-text search
• Use FTS5 operators (AND, OR, NOT)
• Tag-based organization
• Metadata for filtering

---

Available Tools

Core Operations

memory_store

Store a new memory in the current project.

Parameters:

• content (required): The memory content to store
• tags (optional): Array of tags for categorization
• metadata (optional): Object with additional context

Example:

Store a memory: "Authentication uses JWT tokens with 24-hour expiry. Refresh tokens are stored in Redis with 30-day TTL."
Tags: auth, jwt, redis

memory_search

Full-text search across all memories in current project.

Parameters:

• query (required): Search query (supports FTS5 operators)
• limit (optional): Max results to return (default: 10)
• scope (optional): project, global, or all

Example:

Search memories for: authentication AND (jwt OR token)

memory_get

Retrieve a specific memory by ID.

Parameters:

• id (required): Memory ID to retrieve

Example:

Get memory by ID: mem_abc123def456

memory_list

List all memories in current project.

Parameters:

• tags (optional): Filter by tags
• limit (optional): Max results (default: 50)
• offset (optional): Pagination offset

Example:

List all memories tagged with: architecture, database

memory_update

Update an existing memory.

Parameters:

• id (required): Memory ID to update
• content (optional): New content
• tags (optional): New tags
• metadata (optional): New metadata

Example:

Update memory mem_abc123: Change authentication token expiry from 24h to 1h

memory_delete

Delete a memory by ID.

Parameters:

• id (required): Memory ID to delete

Example:

Delete memory: mem_abc123def456

Advanced Operations

memory_get_multiple

Bulk retrieval of multiple memories.

Parameters:

• ids (required): Array of memory IDs

memory_stats

Get database statistics for current project.

Example:

Show Kratos memory statistics

memory_export

Export all project memories to JSON.

Example:

Export all memories to JSON

memory_import

Import memories from JSON file.

Parameters:

• memories (required): Array of memory objects

memory_clear_project

Delete ALL memories for current project (use with caution).

Example:

Clear all Kratos memories for this project

memory_vacuum

Compact and optimize the database.

Example:

Vacuum the Kratos memory database

---

Usage Patterns

Pattern 1: Architectural Decisions

Store:

Store memory: "Decided to use PostgreSQL over MySQL for main database. Reasoning: Better JSON support, stronger ACID compliance, team expertise."
Tags: architecture, database, decision
Metadata: {"date": "2025-01-15", "author": "platform-team"}

Retrieve:

Search memories for: database decision

Pattern 2: Configuration Tracking

Store:

Store memory: "AWX inventory source EPIC-PRO-001 uses conditional_groups for application-based grouping. Key groups: odb, odb_prd, odb_eastus2."
Tags: awx, configuration, inventory
Metadata: {"file": "vars/awx/inventory_sources.yml"}

Retrieve:

Search memories for: AWX inventory configuration

Pattern 3: Technical Debt

Store:

Store memory: "TODO: Refactor authentication middleware to use new JWT library. Current implementation uses deprecated [email protected]. Target: v9.x with ES256 algorithm."
Tags: tech-debt, auth, security
Metadata: {"priority": "high", "file": "src/middleware/auth.ts"}

Retrieve:

List memories tagged: tech-debt, high-priority

Pattern 4: Incident Learnings

Store:

Store memory: "2025-01-10 incident: ODB database connection pool exhaustion caused by long-running queries without timeout. Resolution: Added 30s query timeout in connection config."
Tags: incident, database, odb, postmortem
Metadata: {"date": "2025-01-10", "severity": "high"}

Retrieve:

Search memories for: database incident

Pattern 5: Integration Patterns

Store:

Store memory: "Terraform module azurerm_linux_virtual_machine requires explicit admin_username. Cannot use default 'azureuser' due to security policy. Use 'oemradmin' for all Epic VMs."
Tags: terraform, azure, vm, convention
Metadata: {"module": "ohemr-epic-private-registry-compute-vm"}

Retrieve:

Search memories for: Terraform Azure VM username

---

Best Practices

Memory Content Guidelines

DO:

• Write clear, concise facts
• Include relevant context (dates, file paths, decisions)
• Use consistent terminology
• Add searchable keywords naturally
• Tag for easy categorization

DON'T:

• Store large code blocks (use Serena for code intelligence)
• Write vague statements without context
• Duplicate information already in documentation
• Store temporary information
• Over-tag (3-5 tags is ideal)

Search Optimization

Basic Search:

Search: authentication

Boolean Operators:

Search: authentication AND jwt
Search: database OR redis
Search: auth NOT oauth

Tag Filtering:

List memories tagged: architecture, decision

Phrase Search:

Search: "JWT token expiry"

Memory Lifecycle

Creation:

1. Identify information worth persisting
2. Write atomic, searchable content
3. Add relevant tags (3-5 tags)
4. Include metadata (dates, authors, files)

Maintenance: 5. Review memories monthly 6. Update outdated information 7. Delete obsolete memories 8. Vacuum database quarterly

Retrieval: 9. Search before creating duplicates 10. Use specific search terms 11. Leverage tag filtering 12. Check metadata for context

---

Integration with Other Tools

With Serena (Code Intelligence)

Workflow:
1. Serena → Analyze code structure and symbols
2. Claude → Understand implementation details
3. Kratos → Store architectural decisions
4. Future sessions → Retrieve context from Kratos

Example:

Claude: "Analyze the authentication middleware structure"
Serena: [Returns symbol-level analysis]
Claude: "Store memory: Authentication uses middleware pattern with JWT validation in src/middleware/auth.ts. Tokens validated against Redis cache for revocation."
Tags: architecture, auth, middleware

With otc-awesome-llm (Asset Library)

Workflow:
1. otc-awesome-llm → Provide standard prompts/patterns
2. Claude → Apply pattern to project
3. Kratos → Remember project-specific customizations

Example:

Claude: "Apply Ansible playbook template from otc-awesome-llm"
[Apply template with project-specific vars]
Claude: "Store memory: Ansible playbooks for Epic use custom callback plugins in callback_plugins/ directory. Plugin 'epic_logger.py' formats output for Splunk ingestion."
Tags: ansible, epic, logging

With Context7 (Documentation)

Workflow:
1. Context7 → Fetch current library documentation
2. Claude → Apply to project with customizations
3. Kratos → Remember project-specific usage patterns

Example:

Claude: "Show me azure.azcollection.azure_rm_inventory documentation. use context7"
Context7: [Returns docs]
Claude: "Store memory: azure_rm_inventory source configured with keyed_groups for platform_linux/platform_windows groups based on os_profile tag. See vars/awx/inventory_sources.yml"
Tags: ansible, azure, inventory

---

Troubleshooting

Memory Not Found

Problem: Search returns no results for known content.

Solutions:

1. Check project context (is working directory correct?)
2. Verify memory was stored in current project
3. Try broader search terms
4. List all memories to verify existence

Performance Issues

Problem: Searches are slow (>100ms).

Solutions:

1. Vacuum database: memory_vacuum
2. Check memory count: memory_stats
3. Delete obsolete memories
4. Consider archiving old project

Duplicate Memories

Problem: Multiple similar memories exist.

Solutions:

1. Search before storing new memories
2. Update existing memory instead of creating new
3. Use consistent terminology
4. Review and deduplicate monthly

---

Security Considerations

Data Sensitivity

DO NOT store:

• Passwords or API keys
• PII or sensitive customer data
• Security vulnerabilities (use secure tracking system)
• Confidential business information

Safe to store:

• Architectural decisions
• Configuration patterns
• Code structure insights
• Development conventions
• Technical debt notes

Access Control

Kratos stores memories locally:

• Location: ~/.kratos-mcp/projects/
• Permissions: User-owned, local filesystem
• Isolation: Per-project databases
• No network transmission

---

Performance Targets

Retrieval Speed

• FTS5 search: <10ms typical
• Memory get: <5ms typical
• Memory list: <20ms typical

Capacity Limits

• Recommended: <10,000 memories per project
• Maximum: No hard limit (SQLite scales well)
• Performance degrades beyond 50,000 memories

Database Size

• Average memory: ~500 bytes
• 10,000 memories: ~5 MB database
• Vacuum reduces size by 20-40%

---

Maintenance Tasks

Weekly

• Review new memories for quality
• Search for duplicates

Monthly

• Update outdated memories
• Delete obsolete information
• Review tag consistency

Quarterly

• Vacuum database
• Export backup
• Audit memory relevance

---

Resources

• Installation Guide: docs/kratos-installation.md
• GitHub Repository: https://github.com/ceorkm/kratos-mcp
• MCP Protocol Spec: https://modelcontextprotocol.io/
• SQLite FTS5 Docs: https://www.sqlite.org/fts5.html

---

Support

For issues or questions:

1. Check GitHub Issues
2. Review otc-awesome-llm documentation
3. Contact Epic Platform SRE team