Let's get Ferrosa Memory running.

Two paths to memory

Most people only need one of these. Pick the one that fits how you work.

Option 1 · Agent-driven onboarding

The fastest path. Run one command, then let your AI agent handle the rest.

# Install Ferrosa Memory and download the onboarding guide
curl -fsSL https://ferrosadb.com/setup-memory.sh | bash

Once the server is running, point your MCP client at http://127.0.0.1:18765/mcp and tell your agent:

Onboard me using the ONBOARDING.md file that setup-memory.sh downloaded.

Your agent reads the onboarding guide, configures session hooks, pulls the Nomic embedding model if Ollama is available, wires its own harness config, and verifies the tool list. You watch it work. When it finishes, memory is live and your agent is using it.

Option 2 · Manual setup

If you prefer to control each step, or the agent-driven path hit something it couldn't resolve.

# Ferrosa Database only
curl -fsSL https://ferrosadb.com/install.sh | bash

# Ferrosa Memory plus LLM onboarding
curl -fsSL https://ferrosadb.com/setup-memory.sh | bash

setup-memory.sh installs Ferrosa Database and the long-running Ferrosa Memory HTTP service, downloads the onboarding guide, optionally clones or updates the public repos, and offers to pull the Nomic embedding model. After it finishes, your agent takes over using the onboarding guide.

What you will run

Manual source setup

1. Check prerequisites

rustc --version
cargo --version
git --version
curl --version
python3 --version
ollama --version              # optional semantic search layer
docker compose version        # full Docker stack only
podman compose version        # full Podman stack only

2. Optional Nomic embedding layer

ollama pull nomic-embed-text-v2-moe
ollama list | grep nomic-embed-text-v2-moe

Retrieval defaults

Ferrosa Memory keeps live agent turns compact while evaluation runs use wider candidate generation.

[retrieval]
default_limit = 10

[embeddings]
provider = "ollama"
model = "nomic-embed-text-v2-moe"
dimensions = 768

[eval]
retrieval_k = 25

default_limit = 10 is used when an agent omits limit or k. Lower it with the config MCP tool if memory results are consuming too much context. Eval runs should widen candidate generation in the harness instead of raising the live default.

For evaluation, the harness widens candidate generation rather than raising the live default — for example a wider candidate_limit, a full fusion profile, LLM query decomposition, and embedding variants:

candidate_limit=50
fusion_profile=all
query_decomposition=llm
query_variant_limit=5
query_embed_variants=true
chunk_expansion=none
rerank=false

Tune these in the eval harness for your own corpus; keep the live defaults compact so memory results don't crowd out an agent's working context.

Optional live judge/reranker

[judge]
enabled = false
provider = "ollama"
base_url = "http://127.0.0.1:11434"
model = "qwen2.5-coder:7b"
timeout_seconds = 60

Keep live judge disabled unless a local or remote model endpoint is available. Judge failures and no-decisions are recorded as abstentions, while agent/user feedback can use compact +1 and -1 item scores to tune future rankings by workspace, query shape, and retrieval channel.

3. Clone the public repositories, if contributing from source

mkdir -p ~/src/ferrosa-suite
cd ~/src/ferrosa-suite

git clone https://github.com/ferrosadb/ferrosa.git ferrosa
git clone https://github.com/ferrosadb/ferrosa-memory.git ferrosa-memory

4. Native minimal mode

cd ~/src/ferrosa-suite/ferrosa
cargo build --release

cd ~/src/ferrosa-suite/ferrosa-memory
cargo build --release

Use repository config examples or setup-memory.sh to choose ports, local data directories, credentials, embedding settings, skills, and hooks.

5. Full Compose development stack

cd ~/src/ferrosa-suite/ferrosa
docker build -t ferrosa-memory-node:latest .
# or: podman build -t ferrosa-memory-node:latest .

cd ~/src/ferrosa-suite/ferrosa-memory
docker compose up -d
# or: podman compose up -d

6. Verify health

curl -fsS http://127.0.0.1:18765/healthz/live && echo
curl -fsS http://127.0.0.1:18765/healthz/ready && echo
curl -fsS http://127.0.0.1:18766/viz | head -c 64 && echo

Expected output includes ok, ready, and an HTML doctype from the viz UI.

Connect an MCP client

Now hand your agent the keys. Configure an MCP HTTP server pointing at:

http://127.0.0.1:18765/mcp

Generic MCP server shape:

{
  "name": "ferrosa-memory",
  "transport": "http",
  "url": "http://127.0.0.1:18765/mcp",
  "headers": {
    "Authorization": "Basic <base64 username:password>"
  }
}

Goose

Goose connects to the long-running Ferrosa Memory service over Streamable HTTP. The installer adds or repairs the named extension in ~/.config/goose/config.yaml, preserves other extensions, carries supplied credentials, and is idempotent:

cd ~/src/ferrosa-suite/ferrosa-memory
./setup.sh --harness goose
# or preview only:
python3 scripts/install-agent-hooks.py --harness goose --dry-run

Per-turn recall hooks (Codex, Claude Code, Hermes, Pi)

Beyond the MCP connection, scripts/install-agent-hooks.py wires per-turn recall/capture hooks into supported harnesses so your agent remembers automatically instead of only when it thinks to ask. setup-memory.sh offers this during install; run it directly to add a harness later:

python3 scripts/install-agent-hooks.py --harness auto \
  --mcp-url http://127.0.0.1:18765/mcp

Smoke-test MCP with curl

curl -sS -u ferrosa_user:ferrosa_user \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  http://127.0.0.1:18765/mcp

curl -sS -u ferrosa_user:ferrosa_user \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_stats","arguments":{}}}' \
  http://127.0.0.1:18765/mcp

Ingest and retrieve

This is the payoff. Store a piece of knowledge once, then ask for it back in plain language — your agent gets the relevant memory without re-reading anything. Try these from your agent or the smoke-test tools above.

Ingest a memory entity

{
  "tool": "ingest",
  "arguments": {
    "entity_name": "Project migration rule",
    "entity_type": "decision",
    "content": "Schema migrations should be additive by default so live memory clusters can be upgraded without deleting data."
  }
}

Retrieve related memory

{
  "tool": "search",
  "arguments": {
    "query": "what migration rule did we decide on for live memory clusters",
    "limit": 5
  }
}

Record an evolving fact

{
  "tool": "fact",
  "arguments": {
    "entity_id": "<entity UUID from ingest>",
    "fact_text": "Current rule: prefer additive migrations for live memory clusters."
  }
}

Search raw context segments

{
  "tool": "search_context_segments",
  "arguments": {
    "query": "migration policy additive",
    "limit": 5,
    "expand": {"prev": 1, "next": 1, "max_tokens": 2000}
  }
}

Workbench, hooks, and evals

The workbench at http://127.0.0.1:18765/ includes CQL, SPARQL, Datalog, graph/viz, aliases, rules, approvals, explanations, and Judge Config pages. Use the separate viz page at http://127.0.0.1:18766/viz to inspect linked entities and graph neighborhoods.

The onboarding flow can install Codex, Claude, Hermes, Pi, and Goose client configuration. Lifecycle-capable harnesses receive recall/capture hooks; Goose receives the Streamable HTTP MCP extension. Hooks capture session turns, working directory metadata, and compact retrieval feedback so memories learned in a repository can be preferred when future agents work from the same directory.

cd ~/src/ferrosa-suite/ferrosa-memory
./setup.sh --harness auto

# or run only hook installation
python3 scripts/install-agent-hooks.py --harness auto --verify

Agents should call feedback after retrieval when they can judge returned items: 1 for useful, -1 for irrelevant or wrong, 0 for neutral, and "-" when a judge abstains or fails.

# deterministic harness smoke test
scripts/run-official-evals.sh --self-test

# tune MCP fusion/decomposition profiles
FMEM_EVAL_QUERY_DECOMPOSITION=llm \
FMEM_EVAL_QUERY_EMBED_VARIANTS=true \
scripts/run-fusion-ablations.sh

# start a resumable full-corpus BRIGHT-Pro MCP ingest
scripts/start-bright-pro-full-load.sh

The full-corpus loader writes heartbeat.json, progress.json, and load.log under diagnostics/eval-runs/... so long runs can be monitored or resumed without attaching to a terminal.

Operate safely

Stop and start without deleting data:

cd ~/src/ferrosa-suite/ferrosa-memory
docker compose stop
docker compose start
# or: podman compose stop && podman compose start

After rebuilding an image, recreate nodes one at a time and wait for health before moving on:

docker compose up -d --no-deps --force-recreate node1

Troubleshooting

cd ~/src/ferrosa-suite/ferrosa-memory
docker compose logs --tail=100 node1 node2 node3 ferrosa-memory-mcp

What's new in v0.24.0

Highlights since v0.23.0 — the theme is memories that genuinely survive, and a server that tells you when it can't:

• Global memories now actually persist across sessions. Durable entity types (skills, concepts, decisions, patterns, code symbols, people, places, orgs) were being written under the caller's session partition despite being labeled global — invisible to later sessions. They're now physically stored in the tenant-global partition and readable cross-session.
• Goose support. setup.sh --harness goose installs or repairs Ferrosa Memory as a Streamable HTTP Goose extension end to end (see above).
• Per-turn hooks for Codex, Claude Code, Hermes, and Pi via install-agent-hooks.py, with fail-loud verification: setup sends a representative per-turn write and fails rather than claiming success if it's rejected.
• debug_stop degraded-cluster alerts (opt-in). A background health monitor probes the database and configured embedding/LLM endpoints every 10s; degraded state attaches an alert to tool responses, and quorum loss or a dead provider fails the call outright — so your agent halts instead of building on a broken cluster. Toggle at runtime via the config tool.
• GET /introspect — loopback endpoint returning the server's cluster identity (transport, tenant, keyspace, contact points, ports, version, live reachability) for local controllers like the workbench. No secrets.
• Cross-replica consolidation coordination. Lease-based scheduling so background memory consolidation runs once cluster-wide instead of per-replica.
• Search correctness. Fulltext queries containing English stop words no longer silently return zero results, and the viz graph snapshot defends against non-progressing pagination cursors (reports TRUNCATED instead of streaming forever).
• Non-UUID session IDs (e.g. Hermes agents) map deterministically to stable UUIDs, keeping distinct agent sessions isolated.
• Next release: complete first-run setup. Setup starts Ferrosa before Memory, reconciles the per-install tenant across HTTP auth, viz, and hooks, and registers supported clients consistently. Tenant selection follows the authenticated request; it is not inferred from an arbitrary client value.
• Next release: Forge is installed and validated. Setup builds frg for research and ingestion workflows, verifies its version, then exercises the MCP project_summary and dry-run ingest capabilities. --skip-forge is only for controlled environments that validate Forge separately.

You're up — what next?

Nice work. Once memory is running and connected, here's where to go from here:

• Add Ferrosa Memory as an MCP server to your agent harness, if you haven't already.
• Run the ingest, retrieval, temporal fact, and context segment examples to feel the workflow.
• Use the workbench and viz UI to inspect stored memories and graph links.
• Read How to use for day-to-day patterns once you're set up.
• Run long-horizon evaluation scenarios before making broad reasoning claims.