Audit Logs

Hippocortex Enterprise logs two types of events:

1. Audit logs -- track mutations (create, update, delete) on enterprise resources
2. Access logs -- track memory access decisions made by the policy engine

What Gets Logged

Audit Logs

Every successful mutation (POST, PUT, PATCH, DELETE) on enterprise routes is logged automatically via middleware. Each entry records:

Field	Description
actorType	user or agent
actorId	Who performed the action
action	What was done, e.g., create.team, update.policy, delete.namespace
targetType	Resource type (team, member, agent, namespace, policy, etc.)
targetId	ID of the affected resource
metadata	HTTP method, path, status code
ipAddress	Client IP (from X-Forwarded-For or CF-Connecting-IP)
created_at	Timestamp

Failed requests (non-2xx) are not logged to keep the audit trail clean.

Access Logs

Every policy evaluation during synthesize (and any future policy-checked operation) is logged:

Field	Description
actorType	user or agent
actorId	Who requested access
action	What was requested, e.g., synthesize.read
namespaceId	Target namespace (if scoped)
queryText	The retrieval query (if present)
policyDecision	allow, deny, or default_allow
policiesEvaluated	List of policy IDs that were checked
resultCount	Number of results returned
memoryIds	IDs of memories returned

Querying Audit Logs

curl "https://api.hippocortex.dev/v1/organizations/org_abc123/audit?\
actorId=user_456&\
action=create.team&\
startDate=2026-03-01T00:00:00Z&\
endDate=2026-03-15T00:00:00Z&\
limit=50" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Available Filters

Parameter	Type	Description
actorId	string	Filter by who performed the action
actorType	string	Filter by actor type (user or agent)
action	string	Filter by action (e.g., create.team)
targetType	string	Filter by target resource type
targetId	string	Filter by specific target resource
startDate	ISO date	Only entries after this date
endDate	ISO date	Only entries before this date
limit	number	Max results (default 50, max 200)
offset	number	Pagination offset

Querying Access Logs

curl "https://api.hippocortex.dev/v1/organizations/org_abc123/access-logs?\
policyDecision=deny&\
namespaceId=ns_456&\
limit=50" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "X-Organization-ID: org_abc123"

Available Filters

Parameter	Type	Description
actorId	string	Filter by who requested access
actorType	string	Filter by actor type
action	string	Filter by action
namespaceId	string	Filter by namespace
policyDecision	string	Filter by decision (allow, deny, default_allow)
startDate	ISO date	Only entries after this date
endDate	ISO date	Only entries before this date

Audit Log vs Access Log

	Audit Log	Access Log
What	Resource mutations	Memory access decisions
When	On create/update/delete	On synthesize/retrieval
Why	Compliance, change tracking	Security monitoring, policy debugging
Who	Admin, operator, support	Admin, operator, support

Implementation Details

• Audit logging is fire-and-forget: a failed log insert does not affect the API response
• Audit middleware only runs on enterprise routes (/v1/organizations/:orgId/*)
• Access logs are written by the policy engine and scoped retrieval pipeline
• Both log types are stored in PostgreSQL and queryable via the API