tigunny-memory

Governance-aware agent memory with semantic recall, hash-chained audit, and swarm sync.

Drop production-grade memory into any AI agent project in under 5 minutes. Built for teams that need audit trails, PII protection, and multi-agent coordination out of the box.

Why tigunny-memory?

Raw Qdrant	tigunny-memory
Manual tenant filtering	Structural tenant isolation — impossible to bypass
No PII protection	DLP scanner blocks SSNs, credit cards, API keys automatically
No audit trail	Hash-chained audit log — tamper-evident, SIEM-exportable
Static similarity ranking	Outcome-weighted recall — agents learn which memories actually helped
Single-agent only	Swarm sync — agents share discoveries via Redis pub/sub
DIY injection protection	Prompt injection detector with fast patterns + semantic scan

Quick Start

pip install tigunny-memory
docker run -p 6333:6333 qdrant/qdrant
tigunny-memory init

from tigunny_memory import TigunnyMemory, MemoryConfig

config = MemoryConfig.from_env()

async with TigunnyMemory(config) as mem:
    # Store a memory
    entry = await mem.store(
        agent_id="research-agent",
        content={"task": "market analysis", "result": "Q4 revenue grew 23%"},
        tags=["research", "finance"],
    )

    # Recall relevant memories
    results = await mem.recall("research-agent", "What do we know about revenue?")
    for r in results:
        print(f"[{r.weighted_score:.2f}] {r.memory.content}")

    # Record outcome — improves future recall ranking
    await mem.learn("research-agent", entry.memory_id, outcome_score=0.9)

Installation

# Core (Ollama embeddings, Qdrant, file-based audit)
pip install tigunny-memory

# With specific providers
pip install tigunny-memory[openai]       # OpenAI embeddings
pip install tigunny-memory[voyage]       # Voyage AI embeddings
pip install tigunny-memory[redis]        # Multi-agent swarm sync
pip install tigunny-memory[postgres]     # PostgreSQL audit backend
pip install tigunny-memory[security]     # Semantic injection detection

# Everything
pip install tigunny-memory[all]

Extra	What it enables	Required for
openai	OpenAI text-embedding-3 models	EmbeddingProvider.OPENAI
ollama	Ollama SDK (httpx used by default)	Optional Ollama features
voyage	Voyage AI embeddings	EmbeddingProvider.VOYAGE
postgres	PostgreSQL audit log backend	audit_db_url config
redis	Redis pub/sub swarm sync	enable_swarm_sync=True
security	Claude-based semantic injection scan	Enhanced injection detection
all	All of the above	Full feature set
dev	pytest, ruff, mypy, build tools	Contributing

Configuration

All fields can be set via MemoryConfig or environment variables:

config = MemoryConfig(
    qdrant_url="http://localhost:6333",
    embedding_provider=EmbeddingProvider.OLLAMA,
    tenant_id="my-project",
    max_ttl_days=90,
    enable_dlp=True,
    enable_audit_chain=True,
    enable_injection_detection=True,
    recall_top_k=10,
    outcome_weight=0.3,
)

# Or from environment:
config = MemoryConfig.from_env()  # reads TIGUNNY_MEMORY_* env vars

Env Variable	Default	Description
TIGUNNY_MEMORY_QDRANT_URL	http://localhost:6333	Qdrant server URL
TIGUNNY_MEMORY_EMBEDDING_PROVIDER	ollama	openai, ollama, voyage, custom
TIGUNNY_MEMORY_TENANT_ID	default	Multi-tenant isolation key
TIGUNNY_MEMORY_OPENAI_API_KEY	-	Required for OpenAI embeddings
TIGUNNY_MEMORY_ENABLE_DLP	true	PII/credential scanning
TIGUNNY_MEMORY_ENABLE_AUDIT_CHAIN	true	Hash-chained audit log
TIGUNNY_MEMORY_OUTCOME_WEIGHT	0.3	Outcome influence on recall ranking

Embedding Providers

Provider	Install	Dimensions	Cost	Best for
Ollama	pip install tigunny-memory	768	Free	Dev, air-gapped
OpenAI Small	pip install tigunny-memory[openai]	1,536	~$0.02/1M tokens	Production
OpenAI Large	pip install tigunny-memory[openai]	3,072	~$0.13/1M tokens	High accuracy
Voyage 3	pip install tigunny-memory[voyage]	1,024	~$0.06/1M tokens	Retrieval-optimized
Custom	pip install tigunny-memory	Configurable	Varies	Azure, vLLM, LM Studio

Governance

tigunny-memory enforces governance rules on every operation — no opt-out:

• DLP Scanner: Blocks PII (emails, SSNs, credit cards) and silently redacts API keys/credentials before they reach the vector store
• TTL Enforcement: Memories auto-expire after configurable retention period (default 90 days)
• Size Limits: Prevents memory bloat with configurable content size caps
• Tenant Isolation: Structural filter on every Qdrant query — tenants cannot see each other's data even on misconfiguration

All governance rules work with zero configuration using sensible defaults.

Audit Trail

Every operation writes to a hash-chained audit log (like a blockchain for your agent's memory):

# Verify chain integrity
result = await mem.verify_integrity()
# {"valid": True, "checked": 1247, "broken_at_sequence": None}

# Export for SIEM ingestion
blocks = await mem.export_audit(output_path="./audit.ndjson")

Audit backends:

• File (default): NDJSON file, works anywhere, no DB required
• PostgreSQL (optional): pip install tigunny-memory[postgres], set audit_db_url

Multi-Agent Swarm Sync

pip install tigunny-memory[redis]

config = MemoryConfig(
    enable_swarm_sync=True,
    redis_url="redis://localhost:6379",
    tenant_id="my-project",
)

async with TigunnyMemory(config) as mem:
    # Agent A stores a discovery — all agents in the swarm are notified
    await mem.store("agent-a", {"finding": "competitor launched new product"}, tags=["intel"])

    # Agent B receives the notification and can pull from Qdrant
    # Discovery events share metadata only — not full content (security by design)

Without Redis, NoopSwarmSync is used — zero overhead, no errors.

CLI Reference

tigunny-memory version    # Version + installed optional deps
tigunny-memory health     # Check Qdrant, embeddings, audit backends
tigunny-memory init       # Interactive setup wizard
tigunny-memory store      # --agent <id> --content '{"key":"value"}'
tigunny-memory recall     # --agent <id> --query "search query"
tigunny-memory audit verify   # Verify hash-chain integrity
tigunny-memory audit export   # Export audit log to NDJSON
tigunny-memory stats      # Learning statistics

Framework Integration

FastAPI

from contextlib import asynccontextmanager
from fastapi import FastAPI, Depends
from tigunny_memory import TigunnyMemory, MemoryConfig

memory: TigunnyMemory | None = None

@asynccontextmanager
async def lifespan(app: FastAPI):
    global memory
    memory = TigunnyMemory(MemoryConfig.from_env())
    await memory.connect()
    yield
    await memory.close()

app = FastAPI(lifespan=lifespan)

@app.post("/agent/execute")
async def execute(agent_id: str, task: str):
    relevant = await memory.recall(agent_id, task)
    # ... call LLM with context from relevant memories ...
    entry = await memory.store(agent_id, {"task": task, "result": result})
    return {"memory_id": entry.memory_id}

Security

• Prompt injection detection: Fast regex patterns catch common attacks instantly. Optional semantic scan via Claude Haiku provides deeper analysis.
• Fail-closed: If the semantic scan fails (API error, or a reply with no verdict), content is blocked, not allowed. The verdict is the first JSON object in the classifier's reply that carries injection, so a fenced or annotated reply is read correctly (fixed in 0.1.2; 0.1.0 parsed the whole reply and failed closed on every semantic scan).
• Whose account the scan uses: text longer than 200 characters is sent to Claude under the API key the deployment configures (TIGUNNY_MEMORY_ANTHROPIC_API_KEY). In a customer deployment that is the customer's own Anthropic account, and that data flow should be agreed with the customer before it is turned on. With no key set, only the fast pattern scan runs.
• Memory sanitizer: Every write passes through injection + DLP checks before reaching Qdrant.
• Content hashing: SHA-256 hash of every stored memory for integrity verification.

Enable semantic injection detection:

pip install tigunny-memory[security]
export TIGUNNY_MEMORY_ANTHROPIC_API_KEY=sk-ant-...
export TIGUNNY_MEMORY_ENABLE_INJECTION_DETECTION=true

License

Apache 2.0

Built by Tigunny LLC — SDVOSB · TX HUB Certified.