-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathcli.html
More file actions
135 lines (135 loc) · 65.7 KB
/
cli.html
File metadata and controls
135 lines (135 loc) · 65.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<!doctype html><html lang=en dir=ltr class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-cli" data-has-hydrated=false><head><meta charset=UTF-8><meta name=generator content="Docusaurus v3.10.1"><title data-rh=true>AtomicMemory CLI | AtomicMemory</title><meta data-rh=true name=viewport content="width=device-width, initial-scale=1.0"/><meta data-rh=true name=twitter:card content=summary_large_image /><meta data-rh=true property=og:image content=https://docs.atomicmemory.ai/img/logo-full.svg /><meta data-rh=true name=twitter:image content=https://docs.atomicmemory.ai/img/logo-full.svg /><meta data-rh=true property=og:url content=https://docs.atomicmemory.ai/cli /><meta data-rh=true property=og:locale content=en /><meta data-rh=true name=docusaurus_locale content=en /><meta data-rh=true name=docsearch:language content=en /><meta data-rh=true name=docusaurus_version content=current /><meta data-rh=true name=docusaurus_tag content=docs-default-current /><meta data-rh=true name=docsearch:version content=current /><meta data-rh=true name=docsearch:docusaurus_tag content=docs-default-current /><meta data-rh=true property=og:title content="AtomicMemory CLI | AtomicMemory"/><meta data-rh=true name=description content="atomicmemory is the human- and agent-facing command line for AtomicMemory."/><meta data-rh=true property=og:description content="atomicmemory is the human- and agent-facing command line for AtomicMemory."/><link data-rh=true rel=icon href=/img/logo.svg /><link data-rh=true rel=canonical href=https://docs.atomicmemory.ai/cli /><link data-rh=true rel=alternate href=https://docs.atomicmemory.ai/cli hreflang=en /><link data-rh=true rel=alternate href=https://docs.atomicmemory.ai/cli hreflang=x-default /><link rel=preconnect href=https://fonts.googleapis.com><link rel=preconnect href=https://fonts.gstatic.com crossorigin=anonymous><link rel=stylesheet href="https://fonts.googleapis.com/css2?family=Work+Sans:wght@400;500;600;700;800&family=Fira+Mono:wght@400;500;700&display=swap"><link rel=stylesheet href=/assets/css/styles.224f5720.css /><script src=/assets/js/runtime~main.b62bc408.js defer></script><script src=/assets/js/main.af6c7e72.js defer></script></head><body><svg style="display: none;"><defs>
<symbol id=theme-svg-external-link viewBox="0 0 24 24"><path fill=currentColor d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
</defs></svg>
<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme-87a")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||(window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light")),document.documentElement.setAttribute("data-theme-choice",t||"system")}(),function(){try{for(var[t,e]of new URLSearchParams(window.location.search).entries())if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id=__docusaurus><link rel=preload as=image href=/img/logo-full.svg /><link rel=preload as=image href=/img/logo-full-white.svg /><div role=region aria-label="Skip to main content"><a class=skipToContent_fXgn href=#__docusaurus_skipToContent_fallback>Skip to main content</a></div><nav aria-label=Main class="theme-layout-navbar navbar navbar--fixed-top"><div class=navbar__inner><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded=false class="navbar__toggle clean-btn" type=button><svg width=30 height=30 viewBox="0 0 30 30" aria-hidden=true><path stroke=currentColor stroke-linecap=round stroke-miterlimit=10 stroke-width=2 d="M4 7h22M4 15h22M4 23h22"/></svg></button><a class=navbar__brand href=/><div class=navbar__logo><img src=/img/logo-full.svg alt="AtomicMemory Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"/><img src=/img/logo-full-white.svg alt="AtomicMemory Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"/></div></a><a class="navbar__item navbar__link" href=/>Platform</a><a class="navbar__item navbar__link" href=/sdk/overview>SDK</a><a aria-current=page class="navbar__item navbar__link navbar__link--active" href=/cli>CLI</a><a class="navbar__item navbar__link" href=/integrations/overview>Integrations</a><a class="navbar__item navbar__link" href=/api-reference/http/conventions>API Reference</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><a href=https://github.com/atomicmemory/atomicmemory-core target=_blank rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type=button disabled title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill=currentColor d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill=currentColor d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill=currentColor d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"/></svg></button></div><div class=navbarSearchContainer_Bca1></div></div></div><div role=presentation class=navbar-sidebar__backdrop></div></nav><div id=__docusaurus_skipToContent_fallback class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class=docsWrapper_hBAB><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type=button></button><div class=docRoot_UBD9><main class="docMainContainer_TBSr docMainContainerEnhanced_lQrH"><div class="container padding-top--md padding-bottom--lg"><div class=row><div class="col docItemCol_xLCN"><div class=docItemContainer_jfFK><article><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type=button class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><div class=row><div class="col col--12 markdown"><header><h1 class="anchor anchorTarget_QU3I" id=atomicmemory-cli><a href=#atomicmemory-cli class=headingLink_no4V aria-label="Copy link to AtomicMemory CLI" title="Copy link to AtomicMemory CLI"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>AtomicMemory CLI</span></a></h1></header>
<blockquote data-llms-directive=true>
<p>Agent index: <a href=/llms.txt target=_blank rel="noopener noreferrer" class="">llms.txt</a></p>
</blockquote>
<p><code>atomicmemory</code> is the human- and agent-facing command line for AtomicMemory.
It is separate from the MCP server: <code>atomicmemory-mcp</code> is a stdio process for
agent hosts, while <code>atomicmemory</code> is a normal terminal tool for setup,
diagnostics, memory operations, and stable script output.</p>
<p>The CLI uses the same backend-agnostic SDK provider model as the rest of
AtomicMemory. The current CLI surface supports <code>atomicmemory</code> and <code>mem0</code>.
Additional SDK providers require a CLI adapter, spec, and config-schema update
before they are selectable from command scripts.</p>
<h2 class="anchor anchorTarget_QU3I" id=what-you-get><a href=#what-you-get class=headingLink_no4V aria-label="Copy link to What you get" title="Copy link to What you get"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>What you get</span></a></h2>
<ul>
<li class=""><strong>Interactive terminal dashboard.</strong> Running <code>atomicmemory</code> in a real terminal
opens an Ink UI with a bottom prompt, scrollable session output, slash menu,
and styled diagnostics.</li>
<li class=""><strong>Plain command surface.</strong> Use <code>--no-interactive</code>, non-TTY output, or machine
output modes when you want static text or JSON. Use <code>--interactive</code> as a TTY
rendering hint when text output should open the Ink dashboard.</li>
<li class=""><strong>Setup and diagnostics.</strong> <code>init</code>, <code>doctor</code>, <code>status</code>, <code>validate</code>, <code>config</code>,
<code>hooks</code>, <code>completion</code>, <code>help</code>, and <code>version</code> help operators install, inspect,
and repair local configuration.</li>
<li class=""><strong>Memory workflows.</strong> <code>add</code>, <code>ingest</code>, <code>search</code>, <code>package</code>, <code>list</code>, <code>get</code>,
<code>delete</code>, and <code>import</code> expose the same durable memory primitives used by the
SDK and integrations.</li>
<li class=""><strong>Agent-safe output.</strong> <code>--agent</code> emits stable JSON envelopes for automation.</li>
</ul>
<h2 class="anchor anchorTarget_QU3I" id=install><a href=#install class=headingLink_no4V aria-label="Copy link to Install" title="Copy link to Install"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Install</span></a></h2>
<!-- -->
<div class="theme-admonition theme-admonition-danger admonition_xJq3 alert alert--danger"><div class=admonitionHeading_Gvgb><span class=admonitionIcon_Rf37><svg viewBox="0 0 12 16"><path fill-rule=evenodd d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"/></svg></span>Source-only</div><div class=admonitionContent_BuS1><p><code>@atomicmemory/cli</code> currently depends on the local
<code>@atomicmemory/atomicmemory-sdk</code> checkout. Build and link it from
<a href=https://github.com/atomicstrata/atomicmemory-integrations target=_blank rel="noopener noreferrer" class=""><code>atomicmemory-integrations</code></a>
until the SDK and CLI are published.</div></div><p>Clone <code>atomicmemory-sdk</code> and <code>atomicmemory-integrations</code> side-by-side, then
build the SDK before the CLI:<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>git</span><span class="token plain"> clone https://github.com/atomicstrata/atomicmemory-sdk.git</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>git</span><span class="token plain"> clone https://github.com/atomicstrata/atomicmemory-integrations.git</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">cd</span><span class="token plain"> atomicmemory-sdk</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> build</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">cd</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>..</span><span class="token plain">/atomicmemory-integrations</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--filter</span><span class="token plain"> @atomicmemory/cli build</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">cd</span><span class="token plain"> packages/cli</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>link</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--global</span><br/></div></code></pre></div></div><p>If pnpm has no global bin directory yet:<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> setup</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">source</span><span class="token plain"> ~/.zshrc</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">cd</span><span class="token plain"> /path/to/atomicmemory-integrations/packages/cli</span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>link</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--global</span><br/></div></code></pre></div></div>
<p>You can also run the built binary without global linking:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>node</span><span class="token plain"> /path/to/atomicmemory-integrations/packages/cli/dist/bin.js</span><br/></div></code></pre></div></div>
<h2 class="anchor anchorTarget_QU3I" id=configure><a href=#configure class=headingLink_no4V aria-label="Copy link to Configure" title="Copy link to Configure"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Configure</span></a></h2>
<p>Create a named local profile:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">atomicmemory init </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--profile</span><span class="token plain"> </span><span class="token builtin class-name">local</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--provider</span><span class="token plain"> atomicmemory </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> --api-url http://127.0.0.1:3050 </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> --trust-surface </span><span class="token builtin class-name">local</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--user</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"</span><span class="token string environment constant" style=color:#36acaa>$USER</span><span class="token string" style=color:#e3116c>"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--namespace</span><span class="token plain"> my-project</span><br/></div></code></pre></div></div>
<p><code>--trust-surface</code> is required when the CLI is asked to trust a provider URL
without an existing saved profile. It is not a secret; it describes the
operator boundary around the URL.</p>
<table><thead><tr><th>Value<th>Use when<tbody><tr><td><code>local</code><td>The URL points at a local development service, for example <code>localhost</code>.<tr><td><code>self-hosted</code><td>Your team operates the service and owns the network boundary.<tr><td><code>authenticated-wrapper</code><td>A hosted or shared endpoint is protected by an authenticated wrapper.</table>
<p>For environment-only configuration:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token builtin class-name">export</span><span class="token plain"> </span><span class="token assign-left variable" style=color:#36acaa>ATOMICMEMORY_PROVIDER</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"atomicmemory"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">export</span><span class="token plain"> </span><span class="token assign-left variable" style=color:#36acaa>ATOMICMEMORY_API_URL</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"http://127.0.0.1:3050"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">export</span><span class="token plain"> </span><span class="token assign-left variable" style=color:#36acaa>ATOMICMEMORY_TRUST_SURFACE</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"local"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">export</span><span class="token plain"> </span><span class="token assign-left variable" style=color:#36acaa>ATOMICMEMORY_SCOPE_USER</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"</span><span class="token string environment constant" style=color:#36acaa>$USER</span><span class="token string" style=color:#e3116c>"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token builtin class-name">export</span><span class="token plain"> </span><span class="token assign-left variable" style=color:#36acaa>ATOMICMEMORY_SCOPE_NAMESPACE</span><span class="token operator" style=color:#393A34>=</span><span class="token string" style=color:#e3116c>"my-project"</span><br/></div></code></pre></div></div>
<p>Configuration precedence is:</p>
<ol>
<li class="">CLI flags</li>
<li class=""><code>ATOMICMEMORY_*</code> environment variables</li>
<li class=""><code>~/.atomicmemory/config.json</code></li>
<li class="">command defaults</li>
</ol>
<p><code>atomicmemory config show</code> redacts saved API keys.</p>
<p>API keys should be passed through stdin or environment variables:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token builtin class-name">printf</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>'%s\n'</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"</span><span class="token string variable" style=color:#36acaa>$ATOMICMEMORY_API_KEY</span><span class="token string" style=color:#e3116c>"</span><span class="token plain"> </span><span class="token operator" style=color:#393A34>|</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> atomicmemory init </span><span class="token parameter variable" style=color:#36acaa>--profile</span><span class="token plain"> cloud --api-key-stdin --save-api-key</span><br/></div></code></pre></div></div>
<p>Plain <code>--api-key <value></code> is rejected at parse time so secrets do not land in
shell history. <code>--api-key-stdin</code> provides an ephemeral key for most commands;
for <code>init</code>, pair it with <code>--save-api-key</code> when the key should be persisted to
the named profile.</p>
<p>Memory commands require an explicit scope user from flags, environment, or
config. The CLI does not invent a user for provider-backed operations.</p>
<h2 class="anchor anchorTarget_QU3I" id=interactive-mode><a href=#interactive-mode class=headingLink_no4V aria-label="Copy link to Interactive mode" title="Copy link to Interactive mode"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Interactive mode</span></a></h2>
<p>Run with no arguments in a TTY:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">atomicmemory</span><br/></div></code></pre></div></div>
<p>The dashboard keeps the prompt at the bottom and appends command results above
it. Slash controls are handled by the dashboard:</p>
<table><thead><tr><th>Input<th>Purpose<tbody><tr><td><code>/</code><td>Show the command menu.<tr><td><code>/help</code>, <code>help</code>, <code>?</code><td>Show keyboard controls and command examples.<tr><td><code>/clear</code>, <code>clear</code><td>Clear the session output.<tr><td><code>/quit</code>, <code>/exit</code>, <code>quit</code>, <code>exit</code><td>Exit interactive mode.</table>
<p>Regular CLI commands are typed without a slash:</p>
<table><thead><tr><th>Input<th>Purpose<tbody><tr><td><code>doctor</code><td>Verify local config, package health, and provider readiness.<tr><td><code>status</code><td>Show the active provider, profile, scope, and capability surface.<tr><td><code>config show</code><td>Show the current profile/config in a redacted, readable format.<tr><td><code>add <text></code><td>Store a durable memory.<tr><td><code>search <query></code><td>Search scoped memories.<tr><td><code>package <query></code><td>Build prompt-ready context.</table>
<p>Use <code>PageUp</code> / <code>PageDown</code>, <code>Ctrl+U</code> / <code>Ctrl+D</code>, or the arrow keys to scroll
session output.</p>
<h2 class="anchor anchorTarget_QU3I" id=commands><a href=#commands class=headingLink_no4V aria-label="Copy link to Commands" title="Copy link to Commands"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Commands</span></a></h2>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">atomicmemory doctor</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory status</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory validate</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory validate </span><span class="token parameter variable" style=color:#36acaa>--online</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory </span><span class="token builtin class-name">help</span><span class="token plain"> search</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory version</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory </span><span class="token function" style=color:#d73a49>add</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"The project uses pnpm workspaces."</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory ingest </span><span class="token parameter variable" style=color:#36acaa>--mode</span><span class="token plain"> verbatim </span><span class="token string" style=color:#e3116c>"Decision recap for handoff"</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory ingest </span><span class="token parameter variable" style=color:#36acaa>--mode</span><span class="token plain"> messages </span><span class="token parameter variable" style=color:#36acaa>--file</span><span class="token plain"> ./conversation.json</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory search </span><span class="token string" style=color:#e3116c>"workspace package conventions"</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--limit</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory package </span><span class="token string" style=color:#e3116c>"recent implementation context"</span><span class="token plain"> --token-budget </span><span class="token number" style=color:#36acaa>1200</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory list </span><span class="token parameter variable" style=color:#36acaa>--limit</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>20</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory get </span><span class="token operator" style=color:#393A34><</span><span class="token plain">memory-id</span><span class="token operator" style=color:#393A34>></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory delete </span><span class="token operator" style=color:#393A34><</span><span class="token plain">memory-id</span><span class="token operator" style=color:#393A34>></span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory </span><span class="token function" style=color:#d73a49>import</span><span class="token plain"> ./memories.json</span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory config show</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory config profile list</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory config profile use cloud</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory config profile show </span><span class="token builtin class-name">local</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory skill get core</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory hooks </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--host</span><span class="token plain"> codex </span><span class="token parameter variable" style=color:#36acaa>--runtime</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>node</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory hooks </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--host</span><span class="token plain"> codex </span><span class="token parameter variable" style=color:#36acaa>--runtime</span><span class="token plain"> python</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory hooks run user-prompt-submit </span><span class="token parameter variable" style=color:#36acaa>--host</span><span class="token plain"> codex</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory completion </span><span class="token function" style=color:#d73a49>bash</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory completion </span><span class="token function" style=color:#d73a49>zsh</span><br/></div></code></pre></div></div>
<p><code>validate</code> is the post-install diagnostic. It checks the bundled command spec,
config schema, embedded skill, redaction behavior, and local config-file safety;
<code>--online</code> adds provider connectivity checks.</p>
<p>Provider-backed commands accept the same provider and scope overrides:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">atomicmemory search </span><span class="token string" style=color:#e3116c>"release policy"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--provider</span><span class="token plain"> atomicmemory </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> --api-url http://127.0.0.1:3050 </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> --trust-surface </span><span class="token builtin class-name">local</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--user</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"</span><span class="token string environment constant" style=color:#36acaa>$USER</span><span class="token string" style=color:#e3116c>"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>\</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--namespace</span><span class="token plain"> atomicmemory-integrations</span><br/></div></code></pre></div></div>
<p><code>--trust-surface</code> can be omitted only when an initialized profile already
supplies it.</p>
<h2 class="anchor anchorTarget_QU3I" id=hook-install><a href=#hook-install class=headingLink_no4V aria-label="Copy link to Hook install" title="Copy link to Hook install"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Hook install</span></a></h2>
<p><code>atomicmemory hooks install</code> emits host-specific lifecycle hook config without
mutating user config files. Node is the recommended default and is bundled as
<code>atomicmemory hooks run ...</code>. Python is an advanced option for teams that set
<code>ATOMICMEMORY_PYTHON_HOOK_BIN</code> to a compatible Python hook runner.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">atomicmemory hooks </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--host</span><span class="token plain"> codex </span><span class="token parameter variable" style=color:#36acaa>--runtime</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>node</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory hooks </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--host</span><span class="token plain"> codex </span><span class="token parameter variable" style=color:#36acaa>--runtime</span><span class="token plain"> python</span><br/></div><div class=token-line style=color:#393A34><span class="token plain">atomicmemory hooks </span><span class="token function" style=color:#d73a49>install</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--host</span><span class="token plain"> claude-code </span><span class="token parameter variable" style=color:#36acaa>--runtime</span><span class="token plain"> </span><span class="token function" style=color:#d73a49>node</span><br/></div></code></pre></div></div>
<p><code>hooks run <event></code> is normally invoked by the generated host snippet, not by
operators directly. Supported events are <code>user-prompt-submit</code>, <code>post-compact</code>,
and <code>stop</code>.</p>
<p>Agent hook environments often have a thinner <code>PATH</code> than the interactive shell
that ran <code>atomicmemory hooks install</code>. Before relying on a generated snippet,
confirm the CLI resolves inside the host environment:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token builtin class-name">command</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>-v</span><span class="token plain"> atomicmemory</span><br/></div></code></pre></div></div>
<p>Codex stop payloads are often shorter than Claude Code payloads. The bundled
Node runtime defaults <code>ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS</code> to <code>200</code>; for
Codex hosts, start with <code>40</code> if shorter stop turns should be captured:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token builtin class-name">export</span><span class="token plain"> </span><span class="token assign-left variable" style=color:#36acaa>ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS</span><span class="token operator" style=color:#393A34>=</span><span class="token number" style=color:#36acaa>40</span><br/></div></code></pre></div></div>
<p>The generated snippet does not set this override for you.</p>
<h2 class="anchor anchorTarget_QU3I" id=machine-output><a href=#machine-output class=headingLink_no4V aria-label="Copy link to Machine output" title="Copy link to Machine output"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Machine output</span></a></h2>
<p>Use <code>--json</code> for raw command data and <code>--agent</code> for a stable envelope:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token plain">atomicmemory search </span><span class="token string" style=color:#e3116c>"prior decisions"</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>--agent</span><br/></div></code></pre></div></div>
<p>Envelope shape:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"status"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"success"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"command"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"search"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"duration_ms"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>12</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"profile"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"default"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"scope"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"user"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"pip"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"namespace"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"docs"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"count"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"data"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"memory"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"id"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"mem_123"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"content"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"The docs repo uses pnpm workspaces."</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"scope"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"user"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"pip"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"namespace"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"docs"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"kind"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"fact"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"createdAt"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"2026-05-09T12:00:00.000Z"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"provenance"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"source"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"manual-handoff"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"score"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>0.82</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"meta"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"truncated"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"limit"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>5</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div>
<p><code>provenance</code> is whatever the operator passed through <code>--source</code>,
<code>--source-url</code>, or <code>--source-id</code>; the CLI does not stamp <code>source: "cli"</code>
automatically.</p>
<p>Package results carry both the data-level SDK field and the envelope-level
metadata field:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-json codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"status"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"success"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"command"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"package"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"duration_ms"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>18</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"profile"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"default"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"scope"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"user"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"pip"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"> </span><span class="token property" style=color:#36acaa>"namespace"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"docs"</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"count"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>2</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"data"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"text"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"## Relevant Memory\n..."</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"tokens"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>842</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"hits"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>[</span><span class="token punctuation" style=color:#393A34>]</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"budgetConstrained"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>false</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"meta"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>{</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"token_budget"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token number" style=color:#36acaa>1200</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"format"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"tiered"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"section"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token string" style=color:#e3116c>"inline"</span><span class="token punctuation" style=color:#393A34>,</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token property" style=color:#36acaa>"budget_constrained"</span><span class="token operator" style=color:#393A34>:</span><span class="token plain"> </span><span class="token boolean" style=color:#36acaa>false</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>}</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token punctuation" style=color:#393A34>}</span><br/></div></code></pre></div></div>
<p><code>data</code> is command-specific: memory commands return the sanitized result for that
command, while errors in <code>--agent</code> mode are emitted as JSON and exit non-zero.</p>
<p><code>--interactive</code> is a text-mode rendering hint. It is rejected with exit code 2
when output resolves to a non-text mode such as <code>--json</code>, <code>--agent</code>, or
<code>--output quiet</code>.</p>
<h2 class="anchor anchorTarget_QU3I" id=backend-smoke><a href=#backend-smoke class=headingLink_no4V aria-label="Copy link to Backend smoke" title="Copy link to Backend smoke"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>Backend smoke</span></a></h2>
<p>Backend-gated CLI tests are skipped unless <code>ATOMICMEMORY_TEST_BACKEND=1</code> points
at a real <code>atomicmemory-core</code> instance. To exercise them deterministically
against a local Docker stack, run from <code>atomicmemory-integrations</code>:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>pnpm</span><span class="token plain"> </span><span class="token parameter variable" style=color:#36acaa>-C</span><span class="token plain"> packages/cli test:backend:docker</span><br/></div></code></pre></div></div>
<p>The harness starts a sibling <code>atomicmemory-core</code> Docker stack, layers a
CLI-side mock OpenAI-compatible LLM so ingest tests need no external API
credentials, polls the real <code>/health</code> endpoint with a bounded timeout, runs the
backend-gated suite, and tears the stack down.</p>
<p>Optional harness environment variables:</p>
<table><thead><tr><th>Var<th>Purpose<tbody><tr><td><code>ATOMICMEMORY_CORE_PATH</code><td>Path to the core checkout; defaults to sibling <code>../atomicmemory-core</code>.<tr><td><code>ATOMICMEMORY_DOCKER_APP_PORT</code><td>Host port for core's app; defaults to a free port from <code>3060</code>.<tr><td><code>ATOMICMEMORY_DOCKER_POSTGRES_PORT</code><td>Host port for core's Postgres; defaults to a free port from <code>5444</code>.<tr><td><code>ATOMICMEMORY_DOCKER_HEALTH_TIMEOUT</code><td>Bounded <code>/health</code> poll cap in seconds.<tr><td><code>ATOMICMEMORY_DOCKER_SKIP_BUILD</code><td>Reuse existing compose images when set.<tr><td><code>ATOMICMEMORY_DOCKER_KEEP_UP</code><td>Leave the stack running after the test for inspection when set.</table>
<h2 class="anchor anchorTarget_QU3I" id=see-also><a href=#see-also class=headingLink_no4V aria-label="Copy link to See also" title="Copy link to See also"><span aria-hidden=true data-markdown-ignore=true class=headingIcon_Pk3T>#</span><span class=headingText_IKAy>See also</span></a></h2>
<ul>
<li class=""><a class="" href=/sdk/concepts/provider-model>SDK provider model</a></li>
<li class=""><a class="" href=/sdk/guides/atomicmemory-backend>Using the AtomicMemory backend</a></li>
<li class=""><a class="" href=/integrations/overview>Integrations overview</a></li>
</ul></div></div></div><div class=row><div class="col col--12"><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href=https://github.com/atomicmemory/atomicmemory-docs/edit/main/docs/cli.md target=_blank rel="noopener noreferrer" class=theme-edit-this-page><svg fill=currentColor height=20 width=20 viewBox="0 0 40 40" class=iconEdit_Z9Sw aria-hidden=true><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"/></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></div></div></article><div class=row><div class="col col--12"><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"></nav></div></div></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href=#what-you-get class="table-of-contents__link toc-highlight">What you get</a><li><a href=#install class="table-of-contents__link toc-highlight">Install</a><li><a href=#configure class="table-of-contents__link toc-highlight">Configure</a><li><a href=#interactive-mode class="table-of-contents__link toc-highlight">Interactive mode</a><li><a href=#commands class="table-of-contents__link toc-highlight">Commands</a><li><a href=#hook-install class="table-of-contents__link toc-highlight">Hook install</a><li><a href=#machine-output class="table-of-contents__link toc-highlight">Machine output</a><li><a href=#backend-smoke class="table-of-contents__link toc-highlight">Backend smoke</a><li><a href=#see-also class="table-of-contents__link toc-highlight">See also</a></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Docs</div><ul class="footer__items clean-list"><li class=footer__item><a class=footer__link-item href=/>Introduction</a><li class=footer__item><a class=footer__link-item href=/quickstart>Quickstart</a><li class=footer__item><a class=footer__link-item href=/sdk/overview>SDK</a><li class=footer__item><a class=footer__link-item href=/api-reference/http/ingest-memory>API Reference</a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Code</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/atomicmemory/atomicmemory-core target=_blank rel="noopener noreferrer" class=footer__link-item>atomicmemory-core<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://github.com/atomicmemory/atomicmemory-sdk target=_blank rel="noopener noreferrer" class=footer__link-item>atomicmemory-sdk<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>More</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/atomicmemory target=_blank rel="noopener noreferrer" class=footer__link-item>GitHub<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div></div><div class="footer__bottom text--center"><div class=footer__copyright>Copyright © 2026 AtomicMemory. Apache-2.0 licensed.</div></div></div></footer></div></body>