Astermem

AsterMem

AsterMem runs locally or on the user's own server. It stores private memories with tags, priorities, semantic search and paragraph-level retrieval. Use scripts/astermem.sh on macOS or Linux and scripts/astermem.ps1 on Windows.

Connect once

The CLI reads credentials from ~/.astermem/credentials (Windows: %USERPROFILE%\.astermem\credentials):

ASTERMEM_BASE_URL=http://localhost:8765
ASTERMEM_TOKEN=ast_xxxxxxxx

If the file is missing or the CLI exits with code 2:

1. Start AsterMem with ./start.sh. On Windows, run start.bat.
2. Open Admin → API Tokens and create a token.
3. Write the two lines above into ~/.astermem/credentials.
4. Run scripts/astermem.sh config to verify access.

Do the remaining setup for the user. Do not send them back to Provider forms.

Core commands

scripts/astermem.sh quick "<text>"                 # PREFERRED recall: semantic quick-match, also accepts mem_/trunk_ ids
scripts/astermem.sh search "<query>" [limit]       # broader search
scripts/astermem.sh add "<title>" "<content>" [tags,csv] [priority]
scripts/astermem.sh get <mem_id|trunk_id>
scripts/astermem.sh update <mem_id> <title|content|status|priority> "<value>"
scripts/astermem.sh patch <mem_id> "<old_text>" "<new_text>"   # partial edit, PREFERRED over update content
scripts/astermem.sh delete <mem_id>                # soft delete (archive)
scripts/astermem.sh list [status] [limit]
scripts/astermem.sh tags "tag1,tag2" [limit]
scripts/astermem.sh stats
scripts/astermem.sh config [--catalog]               # redacted provider and search configuration; --catalog adds every selectable provider
scripts/astermem.sh provider <id> '<json_patch>'     # create or update a provider
scripts/astermem.sh test-provider <id>
scripts/astermem.sh rebuild                          # start vector rebuild after explicit confirmation
scripts/astermem.sh rebuild-status
scripts/astermem.sh api <METHOD> </api/path> ['<json>'] [confirm]
scripts/astermem.sh call <tool> '<json>'           # any other tool, see reference.md

On Windows run the same commands through PowerShell, e.g. powershell -ExecutionPolicy Bypass -File scripts/astermem.ps1 quick "<text>".

When a reply is unreadable

Re-running a read command never changes its answer, so treat an unusable reply as a signal to change approach rather than to retry:

• Fields came back null — assume a wrong key path before assuming the service is unconfigured. These replies are nested; print the top-level keys once to see the real shape, or check it in reference.md. Do not re-run the same extraction.
• Output was withheld, truncated or flagged as bulk data by your host — reduce it at the source instead of reformatting the same payload: drop --catalog, lower limit, or fetch one id. Piping through head, jq or a Python script still asks for the same oversized reply.
• Still stuck after two different attempts — stop and tell the user which command failed and how. Do not keep trying variations silently.

Searching again with different keywords is a separate matter and is encouraged; see Memory rules below.

Configure AsterMem for the user

When the user asks to connect a model or set up AsterMem:

1. Run config and read active, providers and provider_catalog_ids. That is enough to see what is set up and which ids are selectable; add --catalog only when you need each entry's base URL and default models.
2. Ask only for missing facts: provider, base URL, embedding model, chat model and API key.
3. Call provider. Example:

scripts/astermem.sh provider asterove '{"api_key":"sk-...","use_for_embedding":true,"use_for_chat":true}'

For a built-in catalog id, this command adds the provider before applying the patch. The JSON patch accepts name, api_type, base_url, api_key_env, api_key, embedding_model, chat_model, vlm_model, use_for_embedding, use_for_chat, semantic_enabled and min_similarity.

min_similarity is a noise floor only (valid range 0–0.4, default 0.15), not a relevance threshold — relevance is judged per query against that query's best hit. Do not raise it to "improve precision": a high floor is what silently reduces semantic search to nothing.

4. Run test-provider <id>. Report the actual embedding and chat test results.
5. If the result says requires_vector_rebuild: true, tell the user the old vectors no longer match. Get confirmation, run rebuild, then check rebuild-status.

Never print an API key back to the user. AsterMem stores keys in its local .env; configuration responses only expose has_api_key.

Operate the whole system

The web UI and AI use the same REST API. Use api for capabilities without a dedicated command:

scripts/astermem.sh api GET /api/tags/tree
scripts/astermem.sh api POST /api/tags/rename '{"old_name":"old","new_name":"new"}'
scripts/astermem.sh api POST /api/import-text '{"content":"...","title":"..."}'
scripts/astermem.sh api GET '/api/knowledge-graph/graph-data'
scripts/astermem.sh api PUT /api/timeline/events/12 '{"status":"completed"}'

Token scopes:

• read: search, statistics, graph, timeline and exports
• write: memories, tags, imports, exploration and timeline updates
• config: providers, semantic search and index rebuilds
• admin: account, Token and log management
• destructive: deletion, clearing data and restart operations

Default Tokens include read, write and config. If an API returns 403, ask the user to create a Token with the missing scope. Never bypass a scope.

Destructive REST calls require the destructive scope and a second confirmation. Restate the action and its impact, get explicit approval, then append confirm:

scripts/astermem.sh api DELETE /api/logs '{}' confirm

For file upload or download endpoints, call the documented REST endpoint with curl or PowerShell and the same Bearer Token. See reference.md.

Memory rules