Set up Synap Core

​

What you need

• Docker with Compose. Give Docker at least 6 GB of memory.
• A way to run a model: an API key for a model provider, or a model you run yourself with Ollama.
• About 8 GB of free disk, for the server image and the models it downloads on the first start.
• Python 3.11 or later, or Node 20 or later, for the SDK.

​

1. Get the server

git clone https://github.com/maximem-ai/maximem_synap_core
cd maximem_synap_core

​

2. Choose your model

cp .env.example .env
chmod 600 .env

SYNAP_LLM_PROVIDER=<the provider you use>
SYNAP_LLM_MODEL=<the model you want>

​

Run a model on your machine

1. Pull the model: ollama pull <the model you want>. Check with ollama list.
2. Make sure the container can reach Ollama. The server runs in Docker and reaches Ollama through host.docker.internal, which the Compose file maps to your machine on Linux as well as on Docker Desktop. Ollama must listen on an address the container can use, not on 127.0.0.1 alone; see Ollama’s own documentation for how to change that, and keep in mind that listening on all addresses exposes Ollama to your network.
3. In .env, set SYNAP_LLM_PROVIDER=ollama and SYNAP_LLM_MODEL=<the exact name you pulled>. You do not need the OpenAI or Anthropic keys.

# a model that can read images
SYNAP_LLM_MODEL_VISION=<a vision model>
# how much text Ollama may read at once, in tokens (default 16384)
OLLAMA_NUM_CTX=16384
# tell compaction the same size, so it sizes its calls to it (without this it assumes 128000 for a model it does not know)
SYNAP_LLM_CONTEXT_WINDOW=16384
# only if Ollama is not at the default address, as seen from the container
OLLAMA_BASE_URL=http://host.docker.internal:11434
# a slow model may need longer than the default 300 seconds to answer
SYNAP_LLM_READ_TIMEOUT_SECONDS=600

​

3. Start it

docker compose -f deploy/docker-compose.yml up -d

docker compose -f deploy/docker-compose.yml logs -f first-start

• It builds the server image on your machine (or pulls the published one).
• It generates the passwords for the databases and keeps them in a Docker volume. They are not in any file you edit.
• It downloads the models, about 2.3 GB in all: the embedding model, a small model that matches names, and a small English text model that splits questions into parts. It checks each file against a fixed checksum. After this first start Synap Core makes no download and does not contact Hugging Face again.
• It creates the database tables and a default client and instance.

​

4. Install the SDK and point it at your server

pip install maximem-synap
export SYNAP_BASE_URL=http://127.0.0.1:8000

npm install @maximem/synap-js-sdk
export SYNAP_BASE_URL=http://127.0.0.1:8000

​

5. Store a memory and read it back

import asyncio
from maximem_synap import MaximemSynapSDK

async def main():
    sdk = MaximemSynapSDK()
    await sdk.initialize()
    try:
        result = await sdk.memories.create(
            document="User: I prefer dark mode.\nAssistant: Noted!",
            document_type="ai-chat-conversation",
            user_id="user_alice",
        )
        await sdk.memories.wait_for_completion(result.ingestion_id)

        context = await sdk.user.context.fetch(
            user_id="user_alice",
            search_query=["preferences"],
        )
        for p in context.preferences:
            print(p.content)
    finally:
        await sdk.shutdown()

asyncio.run(main())

import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient();
await sdk.initialize();
try {
  const result = await sdk.memories.create({
    document: 'User: I prefer dark mode.\nAssistant: Noted!',
    document_type: 'ai-chat-conversation',
    user_id: 'user_alice',
  });
  await sdk.memories.wait_for_completion(result.ingestion_id);

  const context = await sdk.user.context.fetch({
    user_id: 'user_alice',
    search_query: ['preferences'],
  });
  for (const p of context.preferences ?? []) {
    console.log(p.content);
  }
} finally {
  await sdk.shutdown();
}

python3 hello_core.py

node hello-core.mjs

​

6. See what was stored

​

Choose how users are scoped

​

Fit memory to your use case

​

Remove a memory

await sdk.memories.delete(memory_id)

await sdk.memories.delete(memoryId);

result = await sdk.memories.forget(
    description="my old address",
    user_id="user_alice",
    mode="direct",
)
print(result.status, result.deleted_ids)

const result = await sdk.memories.forget({
  description: 'my old address',
  user_id: 'user_alice',
  mode: 'direct',
});
console.log(result.status, result.deleted_ids);

​

Images and files

​

Protect the server

1. Keep the server off the public network: a private network or a firewall.
2. Set SYNAP_API_TOKEN in .env, then run docker compose -f deploy/docker-compose.yml up -d again. Every request must then carry it as a bearer token, your SDK reads it from SYNAP_API_TOKEN in its own environment, and the memory browser asks for it. It is one token for the whole install, not a user identity. When it is not set, the server prints a warning at startup.
3. Use TLS through a reverse proxy on the same machine, and let only the proxy reach the server. The server does not terminate TLS.
4. Back up the Docker volumes for Postgres, Redis, Chroma and Neo4j, the state volume that holds the generated passwords (the databases cannot be opened without it), and the originals/ folder next to deploy/. docker compose down -v deletes the volumes. Test a restore before you rely on a backup.
5. Call it from your own backend, never from a browser or a mobile app.
6. Keep SYNAP_CLOUD_API_KEY out of .env when you are not running the MACA plugin, and revoke it afterwards.

​

Core and Cloud

​

More