Skip to content

Commit df415c8

Browse files
authored
Merge pull request #8 from codeasier/fix/cli-portable-installs
fix(cli): make fresh installs portable and persistent
2 parents bbf42fa + b9ba165 commit df415c8

29 files changed

Lines changed: 2649 additions & 347 deletions

‎.env.example‎

Lines changed: 29 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@
99
# LLM key, no embedding key, no API auth, and no scheduled eviction. Maintenance
1010
# sweeps that only bound internal metadata may be enabled unless marked otherwise.
1111
#
12-
# Run `npx @agentmemory/agentmemory init` to copy this file into place
13-
# automatically. Run `npx @agentmemory/agentmemory doctor` to verify that
14-
# the daemon reads the env you expect.
12+
# Run `npx -y @agentmemory/agentmemory@latest init` to copy this file into
13+
# place automatically. Run `npx -y @agentmemory/agentmemory@latest doctor`
14+
# to verify that the daemon reads the env you expect.
1515
#
1616
# Defaults shown in comments. Listed in priority order — the first key
1717
# present wins on the LLM detection path (see src/config.ts::detectProvider).
@@ -21,8 +21,10 @@
2121
# -----------------------------------------------------------------------------
2222
#
2323
# Without a provider key, agentmemory runs in noop mode: observations are
24-
# indexed via zero-LLM synthetic compression, hybrid search still works,
24+
# indexed via zero-LLM synthetic compression and BM25 recall still works,
2525
# but LLM-backed summarisation / reflection / consolidation are disabled.
26+
# A provider key alone does not enable LLM-written observation compression;
27+
# that path also requires AGENTMEMORY_AUTO_COMPRESS=true.
2628
# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
2729
# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
2830

@@ -64,10 +66,14 @@
6466
# 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
6567
# -----------------------------------------------------------------------------
6668
#
67-
# Without an embedding key, agentmemory runs in BM25-only mode for hybrid
68-
# search. Detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
69+
# Without an embedding provider, vector embeddings are disabled. `mem::search`
70+
# uses BM25; `mem::smart-search` can also fuse structural graph matches when
71+
# graph data exists. Remote
72+
# provider detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
6973
# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
70-
# local (Xenova/all-MiniLM-L6-v2, 384-dim).
74+
# BM25-only. Local embeddings are an explicit opt-in, not the keyless default.
75+
# `EMBEDDING_PROVIDER=local` uses Xenova/all-MiniLM-L6-v2 (384-dim) on-device;
76+
# the first embedding request downloads the model and needs network access.
7177

7278
# EMBEDDING_PROVIDER=local # local | openai | voyage | cohere | gemini | openrouter
7379

@@ -107,7 +113,7 @@
107113
# 5. Behaviour flags
108114
# -----------------------------------------------------------------------------
109115

110-
# AGENTMEMORY_AUTO_COMPRESS=true # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
116+
# AGENTMEMORY_AUTO_COMPRESS=true # Run LLM-written compression on every observation batch. Requires BOTH this flag and a configured provider; a provider alone leaves synthetic compression active.
111117
# AGENTMEMORY_INJECT_CONTEXT=true # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
112118
# CONSOLIDATION_ENABLED=false # Runs by default with an LLM provider; set false to opt out of the 4-tier pipeline.
113119
# CONSOLIDATION_DECAY_DAYS=30 # Age (days) after which non-reinforced memories decay during consolidation
@@ -150,6 +156,13 @@
150156
# AGENTMEMORY_PROBE_TIMEOUT_MS=2000 # MCP shim livez probe timeout
151157
# AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim
152158
# AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status`
159+
# Persistent iii state; same override as `--data-dir`, used by native and
160+
# Docker starts. Explicit flag/env wins. Otherwise instance 0 reuses an
161+
# existing ./data/state_store.db or ./data/iii-config.yaml before defaults: macOS
162+
# ~/Library/Application Support/agentmemory; Linux $XDG_DATA_HOME/agentmemory
163+
# or ~/.local/share/agentmemory; Windows %APPDATA%\agentmemory.
164+
# AGENTMEMORY_DATA_DIR=/absolute/path
165+
# AGENTMEMORY_USE_DOCKER=1 # Prefer bundled Docker even when a compatible native iii binary exists
153166
# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Default destination for `agentmemory export`
154167

155168
# STANDALONE_MCP=1 # MCP shim only — bypass the worker and run @agentmemory/mcp in-process
@@ -169,9 +182,14 @@
169182
# 7. Ports
170183
# -----------------------------------------------------------------------------
171184

172-
# III_REST_PORT=3111 # REST API port (also affects viewer at +2)
173-
# III_STREAMS_PORT=3112 # Streams API port
174-
# III_ENGINE_URL=ws://localhost:49134 # iii-engine WebSocket URL (used by the worker)
185+
# III_REST_PORT=3111 # REST API + MCP HTTP anchor
186+
# III_STREAM_PORT=3112 # Preferred streams override; defaults to REST + 1
187+
# III_STREAMS_PORT=3112 # Legacy alias for III_STREAM_PORT
188+
# III_VIEWER_PORT=3113 # Viewer bind port; defaults to REST + 2
189+
# III_ENGINE_PORT=49134 # Engine bind port; defaults to REST + 46023
190+
# III_ENGINE_URL=ws://localhost:49134 # Explicit/remote worker WebSocket URL; takes precedence over derived engine port
191+
# Derivation applies only while the corresponding explicit port/URL is unset.
192+
# `--instance 1` selects 3211/3212/3213/49234 and an instance-1 data subdir.
175193

176194
# -----------------------------------------------------------------------------
177195
# 8. iii engine pin

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
1212

1313
### Fixed
1414

15+
- **Fresh installs are portable and persistent (aligned with upstream #892).** The bundled `iii-config.yaml` uses cwd-relative paths and the engine was spawned without a cwd, so on global and npx installs `./data/state_store.db` and `./data/stream_store` landed in whatever directory the user ran the CLI from, and the `iii-exec` supervision block never resolved — nothing respawned the worker after it died, which surfaced as "all data gone" reports against a live REST port. `agentmemory start` now regenerates a runtime config each boot (`~/.agentmemory/data/iii-config.runtime.yaml`) with absolute data paths and an absolute worker exec line, anchors the engine cwd at `~/.agentmemory`, and copies any legacy `./data` stores from the invocation directory on first run. Repo checkouts keep the cwd config and repo-root cwd, so dev behavior is unchanged; user overrides via env or `~/.agentmemory/iii-config.yaml` are passed through verbatim. The viewer port is now configurable (`III_VIEWER_PORT`, default REST + 2), worker pidfile paths honor `AGENTMEMORY_RUNTIME_DIR`, Docker installs gain uid/gid/chown controls, and `agentmemory remove` covers the generated runtime config. `agentmemory doctor` and startup-failure reporting were expanded accordingly.
1516
- **Observation capture no longer grows the persisted live-stream store.** Raw and compressed observation events use `stream::send` instead of `stream::set`; the viewer still receives live updates and REST remains the history source, but `data/stream_store` no longer accumulates a write-only second and third copy of every observation.
1617
- **Server-side capture payloads are bounded without flattening structured tool data.** `tool_input`, `tool_output`, prompts and the raw envelope are trimmed to configurable character budgets (`AGENTMEMORY_OBSERVE_*`); object fields such as `file_path` survive truncation, `0` disables an individual bound, and positive budgets below 2 are clamped to the smallest serialized string.
1718
- **Graph and semantic provenance are bounded.** Graph nodes, edges, insights and semantic session provenance keep only the freshest source ids instead of growing for the life of the session.

0 commit comments

Comments
 (0)