Mike AGENTS.md

AGENTS.md - Institutional Memory Agent

Brief for AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) picking up this project. Read top-to-bottom before making changes. The gotchas section below encodes the debugging we already went through - skip it and you'll relearn each one.

For the public-facing project overview, see README.md. For the design diagram and data flow, see ARCHITECTURE.md. This file is the operational handoff.

---

0. One-paragraph orientation

ima ("Institutional Memory Agent") is a Splunk-native system that captures SOC analyst reasoning on alert closures, persists it to Splunk KV Store, and exposes the resulting institutional knowledge graph through four surfaces: a Python CLI, custom search commands inside Splunk, a Splunk modular input that runs autonomously, and a Model Context Protocol (MCP) server for external AI agents. The LLM extraction step is built against Splunk's hosted Foundation-Sec-1.1-8B; locally it runs Llama-3.1-8B-Instruct via Ollama as a stand-in (swap is a one-line .env change).

See section 7 for the full coding/writing conventions to follow on any change.

---

1. Run it locally (commands that always work)

# from repo root, after bootstrap
.\.venv\Scripts\Activate.ps1

ima auth check                                       # verify Splunk REST is reachable
ima kv init                                          # create KV Store collections
ima demo seed --clear                                # wipe + seed 10 realistic annotations
ima knowledge build                                  # cluster via Ollama, ~3 min on CPU
ima knowledge query "finance Monday"                 # semantic-search the graph
ima knowledge about acct-prod-01                     # per-asset memory card
ima alerts watch --interval 0 --earliest -10m        # single-pass poll for unannotated alerts
ima mcp serve                                        # stdio MCP server (Claude Desktop)
ima mcp serve --http --port 8765                     # HTTP MCP server (remote agents)