Hippocortex OS — Beta FAQ

Answers to common questions from beta users.

General

What is Hippocortex?

Hippocortex is a memory layer for AI agents. It captures what your agent does, learns patterns from that history, and synthesizes relevant context when your agent needs to make decisions. Think of it as giving your agent a persistent, structured brain that remembers across sessions.

What Hippocortex is NOT

Not an LLM. It does not generate text.
Not a vector database. It uses vector search internally but offers much more (episodic traces, graph memory, conflict detection, governance).
Not a chatbot framework. It handles memory only, not conversation routing or UI.
Not multi-tenant. Each instance serves one agent or user.

What language models does it work with?

All of them. Hippocortex is model-agnostic. It captures events and returns context as structured data. You feed that context to whatever LLM you use (GPT-4, Claude, Gemini, Llama, Mistral, etc.).

Does Hippocortex call any external APIs?

No. The server is fully self-contained. It does not call any external services, LLMs, or APIs. All processing happens locally.

Setup & Deployment

Do I need a GPU?

No. Hippocortex does not run ML models. It runs on CPU only.

What are the minimum system requirements?

2 CPU cores, 2 GB RAM, 10 GB disk, Node.js 22+. A $5/month VPS can run it.

Can I run it on my laptop?

Yes. Docker or local Node.js both work on macOS, Linux, and WSL2.

Do I need a domain name and HTTPS?

Not for local development. For production use, we recommend Caddy as a reverse proxy which handles TLS automatically.

Can I run it in the cloud?

Yes. Any VPS, EC2 instance, or cloud VM works. Docker is recommended.

Data & Privacy

Where is my data stored?

Locally, on your machine. Hippocortex stores everything in a single SQLite file on disk. Nothing is transmitted anywhere.

Do you collect any telemetry?

No. The beta server sends zero data to us. We only see what you explicitly share through feedback forms or support conversations.

Can I export my data?

Yes. The SQLite database is a standard file. You can copy it, query it with any SQLite tool, or back it up freely.

Can I delete specific memories?

Yes. The governance subsystem supports targeted deletion with audit trails (tombstones) that prevent deleted data from being recreated. Deletion is real, not soft-delete.

What happens to my data after the beta?

Your data stays on your machine. If you stop using Hippocortex, your data remains in the SQLite file until you delete it. We have no access to it.

Integration

How do I connect my agent to Hippocortex?

Install the SDK (npm install @hippocortex/sdk or pip install hippocortex), initialize it with your API key and server URL, then call capture(), learn(), and synthesize() from your agent code. See BETA-QUICKSTART.md.

Can I use the REST API directly without the SDK?

Yes. The server exposes a standard REST API. The SDK is a thin wrapper. Key endpoints:

POST /api/v1/capture      — Record an event
POST /api/v1/learn        — Trigger memory consolidation
POST /api/v1/synthesize   — Retrieve context
GET  /api/v1/health       — Health check

How often should I call `learn()`?

After each agent session ends, or every 15–60 minutes for long-running agents. Do not call it more than once per minute — consolidation is CPU-intensive.

How often should I call `synthesize()`?

Before each LLM call where you want memory context. It's fast (p95 < 500ms) and designed to be called frequently.

Does Hippocortex slow down my agent?

Minimally. capture() is async and returns in <200ms (p95). synthesize() returns in <500ms (p95). Neither blocks your agent's main loop if called asynchronously.

What event types can I capture?

message — User or assistant messages
tool_call — Agent invoking a tool
tool_result — Tool returning a result
file_edit — File creation or modification
test_run — Test execution results
command_exec — Shell command execution
Custom types are supported via the metadata field

Can I use Hippocortex with multiple agents?

In v1, one Hippocortex instance = one memory space. For multiple agents with separate memories, run multiple instances. Shared memory across agents is not supported yet.

Troubleshooting

The server won't start

Check the error output. Common causes:

Port 3100 already in use (lsof -i :3100)
Node.js version too old (need 22+)
Storage path not writable

See BETA-TROUBLESHOOTING.md for detailed resolution steps.

I'm getting 401 Unauthorized

Your API key doesn't match. Check:

HIPPOCORTEX_API_KEYS env var includes your key
You're sending the key as X-API-Key header (not Authorization)
No extra whitespace in the key

My agent is slower after integration

Check if you're calling learn() synchronously in the request path. Move it to a background job or post-session hook.

I'm seeing "conflict detected" in logs

This is normal. Hippocortex detected contradictory information (e.g., "user prefers dark mode" vs "user prefers light mode") and quarantined it. The most recent information wins by default, but you can customize conflict resolution.

Beta Program

How long does the beta last?

4–5 weeks. See the beta plan for the exact timeline.

What feedback do you want?

Structured feedback via the evaluation scorecard (provided at Day 14). We care most about:

Was integration easy or painful?
Did memory retrieval return useful context?
What broke or confused you?
Would you keep using it?

Can I share Hippocortex with my team?

During the beta, please limit usage to the invited individual. We want focused feedback, not broad distribution.

Will there be breaking changes during beta?

Possible but unlikely. If we ship a fix that changes the API, we'll notify you with migration steps before you update.

What happens after the beta?

Based on feedback, we'll either expand the beta, prepare for GA release, or address blockers first. Beta users get early access to GA and input on the roadmap.