# Background Intelligence (/docs/advanced-features)
Background Intelligence is how Mem becomes more than a storage layer.
You save memories, threads, and documents. Then the system keeps working on them: linking related ideas, surfacing contradictions, synthesizing clusters, and writing a daily briefing your connected tools can read.
You save a decision about PostgreSQL in January. In July, you record that you're migrating to CockroachDB. Six months apart, different contexts. Nowledge Mem links them, tracks the evolution, and the next time you search for either, both appear with the full trail of how your thinking changed.
This runs in the background. You open the app and the connections are there.
Do not try to validate every background feature at once. The first useful proof is simpler: save enough real knowledge that Mem can show you one relevant briefing item, one non-obvious connection, or one contradiction you had not surfaced yourself.
Background Intelligence requires a configured Remote LLM and the appropriate license for your build. Enable it in **Settings > Knowledge Processing**.
## The First Useful Sign [#the-first-useful-sign]
You know Background Intelligence is becoming useful when Mem shows you something you probably would not have found on your own:
* a contradiction between old and new thinking
* a cluster of related work across time
* a morning briefing that is actually relevant
## Knowledge Graph [#knowledge-graph]
Every memory becomes a node in a graph. The system extracts entities (people, technologies, concepts, projects) and maps how they relate to each other and to your existing knowledge.
The result: search "distributed systems" and find your memory about "Node.js microservices." The words don't match. The meaning does.
With Background Intelligence enabled, extraction runs automatically for new memories. You can also trigger it manually for older ones.
### What Gets Extracted [#what-gets-extracted]
When a memory is processed, the LLM identifies:
* **Entities**: people, technologies, concepts, organizations, projects
* **Relationships**: how those entities connect
* **Links to existing knowledge**: connections to memories already in the graph
Trigger extraction for any memory by clicking **Knowledge Graph** on its card.
### Knowledge Evolution [#knowledge-evolution]
When you save something new about a topic you've written about before, the system detects the relationship and creates a version link:
| Link type | Meaning | Example |
| -------------- | ---------------------- | ------------------------------------------------------------------- |
| **Replaces** | You changed your mind | "Use CockroachDB" replaces "Use PostgreSQL" |
| **Enriches** | You added depth | "React 19 adds a compiler" enriches "React 18 concurrent rendering" |
| **Confirms** | Independent agreement | Two separate reviews recommend the same library |
| **Challenges** | Contradiction detected | Your March assessment disagrees with your October conclusion |
You can trace how your understanding of any topic changed over time.
### Community Detection [#community-detection]
Graph algorithms find natural clusters in your knowledge: groups of tightly connected memories that form coherent topics. Your graph might reveal clusters for "React Patterns," "API Design," and "Database Optimization." A map of your expertise you never drew by hand.
In **Graph View**, click **Compute** to run community detection.
## Visual Exploration [#visual-exploration]
Your knowledge as an interactive network. Click a memory to see its connections. Zoom into clusters. Follow links between topics you never thought to compare.
The timeline slider filters by date range. Watch how your knowledge in a domain grew over weeks or months.
## What the System Discovers [#what-the-system-discovers]
The graph is the foundation. On top of it, Background Intelligence actively analyzes your knowledge and surfaces findings in the Timeline.
### Insights [#insights]
Insights are connections you wouldn't have found on your own.
* **Cross-domain links.** In March you noted that JWT refresh tokens were causing race conditions in the payment service. In September you chose the same token rotation pattern for a new auth service. The system catches it: same failure pattern, different project.
* **Temporal patterns.** "You've revisited this database migration decision 3 times in 2 months." Maybe it's time to commit.
* **Forgotten context.** "Your March assessment contradicts the approach you chose in October." The system remembers what you wrote, even when you don't.
Every insight cites its sources so you can trace the reasoning.
One insight that changes how you think beats ten that state the obvious. Strict quality gates keep the noise out.
### Crystals [#crystals]
Five memories about React patterns saved over three months. Scattered across your timeline. Hard to piece together.
A crystal synthesizes them into one reference article. Sources are cited. When you save new related information, the crystal updates.
Crystals appear when the system has enough material to say something useful. You don't request them.
### Flags [#flags]
Sometimes the system finds problems, not connections:
| Flag | What it means | Example |
| ---------------------- | -------------------------------- | ----------------------------------------------------------------- |
| **Contradiction** | Two memories disagree | "Use JWT tokens" vs. "Session cookies are more secure" |
| **Stale** | Newer knowledge supersedes older | A deployment guide from 6 months ago, overwritten by recent notes |
| **Needs verification** | Strong claim, no corroboration | A single memory making an assertion with no supporting evidence |
Each flag appears in the Timeline. You can dismiss it, acknowledge it, or link it to a resolution.
### Working Memory [#working-memory]
Each morning, Mem writes a Working Memory briefing for the current space:
* **Active topics** based on recent activity
* **Unresolved flags** needing attention
* **Recent changes** in your knowledge base
* **Priority items** by frequency and recency
Connected AI tools can load this briefing through their own connector path at session start. MCP is one path, but native connectors and other packaged setups can do the same.
The **Default** space keeps the familiar compatibility file at `~/ai-now/memory.md`. If you turn on [Spaces](/docs/spaces), other spaces get their own Working Memory briefings behind the same Mem APIs and connectors.
You can still edit Working Memory directly. Your changes are respected.
Connected AI tools can load Working Memory through MCP, native connectors, or other packaged paths. When a tool knows the active space, it reads the right briefing automatically.
## Configuration [#configuration]
Control background processing in **Settings > Knowledge Processing**:
| Setting | Default | What it controls |
| --------------------------- | ----------------- | ----------------------------------------------------- |
| **Background Intelligence** | Off | Master toggle for all background processing |
| **Daily Briefing** | On (when enabled) | Morning Working Memory generation |
| **Briefing Hour** | 8 | What hour the daily briefing runs (local time) |
| **Auto Extraction** | On (when enabled) | Automatic knowledge graph enrichment for new memories |
On Linux servers, configure via CLI:
```bash
nmem config settings set backgroundIntelligence true
nmem config settings set autoDailyBriefing true
nmem config settings set briefingHour 8
```
## Next Steps [#next-steps]
* **[Memories](/docs/memories)**: Create, search, organize, and connect your knowledge
* **[Threads](/docs/threads)**: Capture, browse, and distill AI conversations
* **[Getting Started](/docs/getting-started)**: The Timeline, document import, and all ways to add knowledge
* **[Connectors](/docs/integrations)**: Connect your AI tools through native connectors, reusable packages, MCP, and browser capture
* **[Troubleshooting](/docs/troubleshooting)**: Common issues and solutions
# Context (/docs/ai-context)
Context is where you check what a connected AI will see before it starts: who you are, which AI profile it is using, which memories it can use, standing rules, and Working Memory.
Think of it as the start card Mem hands to your AI tools.
## How It Fits With The Rest Of Mem [#how-it-fits-with-the-rest-of-mem]
Memories, Threads, Library, Skills, Spaces, and AI Now each do a different job. Context does not replace them. It shows how they come together for a specific AI run.
| View | What it is for |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Memories** | Durable facts, preferences, decisions, plans, procedures, learnings, events, and context worth keeping |
| **Threads** | Saved conversations and exact discussion history |
| **Library** | Files, documents, sources, and generated artifacts |
| **[Skills](/docs/concepts/skills)** | Repeatable ways your AI should perform a task |
| **Spaces** | The memory lane a project, tool, or long-running agent should use |
| **AI Now** | The place where you work directly with Mem's built-in AI |
| **Context** | The preview and editor for what connected AI tools receive before they start |
## The First Useful Move [#the-first-useful-move]
Open **Context → Preview**.
You should see a sentence like:
> Default AI receives your profile, Working Memory, and no rules. It can use memories only from Default.
If that sentence matches what you expect, you do not need to configure anything else.
## What You Can Change Here [#what-you-can-change-here]
* **You**: your name, aliases, language, and personal context
* **AI Profiles**: named long-running agents, each with an optional default space and profile-specific rules
* **Rules**: standing behavior rules that apply to everyone, one AI profile, or one space
* **Spaces**: memory scope, shared context, and space-level rules
Every change should be visible back in **Preview**.
## When To Create An AI Profile [#when-to-create-an-ai-profile]
Do it when an AI has a stable role over time:
* a reviewer that always checks code quality
* an onboarding assistant that explains slowly
* a research agent that should stay in one project space
Do not create a profile for every temporary chat. The default AI profile is enough for normal use.
## How Connected Tools Use It [#how-connected-tools-use-it]
Supported connectors read the Context Bundle at session start when they can. It includes Context plus the current Working Memory. Older or simpler integrations may read only Working Memory as a lightweight fallback.
For multi-agent tools, the profile is selected only when the tool passes an explicit Mem agent ID or stable host agent ID. The tool name itself, such as `codex` or `claude-code`, is only provenance.
## What Not To Worry About Yet [#what-not-to-worry-about-yet]
* Context is not a new memory type.
* It is not indexed or embedded.
* Changing it does not require search reindexing.
* You do not need to understand Context Bundle, MCP, or KFS paths to use the page.
## Next Steps [#next-steps]
* [Your Profile](/docs/profile) if the AI does not know enough about you yet
* [AI Profiles](/docs/concepts/ai-profiles) if a long-running agent needs its own identity
* [Rules](/docs/concepts/rules) if you want behavior that applies before search or Skills
* [Spaces](/docs/spaces) if two projects or agents need different memory lanes
* [Connectors](/docs/integrations) if you want another AI tool to use this context
# AI Now (/docs/ai-now)
AI Now is the place where you work directly with your saved knowledge. It runs with your Mem server, so the desktop app, web app, and mobile clients can see the same AI Now sessions when they connect to that server.
Instead of starting from a blank prompt every time, AI Now starts from what you already know. That makes it useful for research, analysis, presentations, and longer multi-step tasks that should build on your own history rather than generic model output.
AI Now requires a configured **Remote LLM**.
Go to **Settings** → **Remote LLM** to set up, refer to [Remote LLMs](/docs/usage#remote-llms) for details.
If you're connected to another Nowledge Mem via [Access Anywhere](/docs/remote-access), AI Now uses that server's LLM configuration. You do not need to configure a separate provider on each client.
## The First Useful Task [#the-first-useful-task]
If you are opening AI Now for the first time, start with something grounded in your own knowledge:
> What architecture decisions have I made about caching?
That is a better first task than a generic prompt because it lets you see the product model immediately:
* AI Now reads from your saved knowledge
* it can pull in files or enabled plugins when relevant
* it can turn the result back into updated knowledge if needed
You know AI Now is set up correctly when one grounded question about your own work gets a useful answer without you re-explaining everything from scratch.
## What AI Now Can Do [#what-ai-now-can-do]
| Category | What it does |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Memory Search** | Finds relevant memories with semantic understanding |
| **[Library Search](/docs/library)** | Searches, reads, and analyzes documents you imported into the Library: PDFs, spreadsheets, Word files, slides, code |
| **Deep Research** | Multi-source research combining your memories and web search |
| **File Analysis** | Analyzes Excel, CSV, Word, PDF files you provide |
| **Data Visualization** | Generates charts from your data |
| **Presentations** | Creates slides with live preview and PowerPoint export |
| **Travel Planning** | Creates interactive day-by-day itineraries |
| **Connectors** | Connects to Notion, Obsidian, Apple Notes, and custom MCP plugins |
## Getting Started [#getting-started]
### Configure Remote LLM [#configure-remote-llm-step]
Go to **Settings** → **Remote LLM** and add your API key.
### Open AI Now [#open-ai-now-step]
Click the **AI Now** tab in the sidebar, or press Cmd/Ctrl + 5.
### Start a Grounded Task [#start-a-grounded-task-step]
Start with a task that matches the context you have already given Mem:
> What architecture decisions have I made about caching?
When relevant, it pulls from your memories, searches the web, and uses any connected notes or enabled plugins you have configured.
You can also drop files or folders for analysis, request reports based on your recent work, or run a deep study on any topic.
As it works, AI Now can also create or update memories when that is useful.
If you use [Spaces](/docs/spaces), AI Now follows the space currently selected in the app. That lets one AI Now session stay focused on a project or agent context without changing how the rest of Mem works.
## Mention memories in your chat [#mention-memories-in-your-chat]
Use @ to search and reference specific memories in your conversation.
## Deep Research [#deep-research]
For comprehensive research, AI Now runs parallel sub-tasks across multiple sources and synthesizes the results.
Click the Research toggle in the AI Now chat interface.
### How It Works [#how-it-works]
Ask a research question:
> Research the current state of quantum error correction
AI Now will:
1. Search your memories for existing knowledge on the topic
2. Search the web from multiple angles
3. Synthesize findings into a single answer
4. Cite sources with reliability indicators
## Optional Skills [#optional-skills]
Skills are specialized capabilities you enable for specific tasks.
| Skill | What it enables |
| ------------------------ | ------------------------------------------------------------------- |
| **Documents** | Excel/CSV analysis, chart generation, file operations |
| **Presentation Creator** | Slide generation with live preview and export |
| **Travel Planner** | Interactive itinerary creation |
| **Browse Now** | Real-browser automation for authenticated and interactive web tasks |
Enable skills in **AI Now** → **Plugins** → **Skills**.
### File Analysis [#file-analysis]
Attach files or folders to your conversation for analysis.
When you send the message, AI Now copies those attachments into the current
task workspace under `inputs/`. The agent reads that workspace copy and writes
new charts, scripts, reports, or slides back into the same task folder.
If you are connected to your Mem server through Access Anywhere, the App or Web
client securely uploads the selected files into that task before AI Now starts.
The server works from its own copy, so the original path does not need to exist
on the server. If file attachment is unavailable for a hosted workspace, add the
file to your Library and reference it from there.
Toggle the Documents SKILL in AI Now Plugins to enable.
#### Supported Files [#supported-files]
| Type | Extensions | What AI Now Does |
| ---------------- | ------------------- | -------------------------------------------------- |
| **Spreadsheets** | .xlsx, .xls, .csv | Analyzes data, finds patterns, generates charts |
| **Documents** | .docx, .doc, .pdf | Summarizes, extracts key points, answers questions |
| **Code** | .py, .js, .ts, etc. | Reviews, explains, suggests improvements |
#### Example [#example]
1. Attach `sales_q4.xlsx`
2. Ask: "What are the top 3 trends in this data?"
3. AI Now analyzes and generates visualizations
Whole folders work too.
### Presentations [#presentations]
Toggle the Presentation SKILL in AI Now Plugins to enable.
> Create a presentation based on our above study and research, include some charts or diagrams to support the insights
AI Now generates slides with structure, charts, and insights from your conversation.
Refine with follow-up requests ("Make the third slide more visual", "Add a slide about customer segments"), or click Edit to edit directly.
Export as PowerPoint with the PPTX button.
### Travel Planning [#travel-planning]
Toggle the Travel Planner SKILL in AI Now Plugins to enable.
> Plan a 5-day trip to Tokyo focusing on food and culture
AI Now generates an interactive day-by-day itinerary using your recent memories and web research as context.
### Browse Now [#browse-now]
Toggle the Browse Now skill in **AI Now** → **Plugins** → **Skills** to let AI Now use your real browser for authenticated or dynamic pages.
Turn this on when a task needs your actual browser session, not a generic fetch. Typical cases:
* logged-in websites
* clicking, typing, scrolling, or multi-step flows
* screenshots or rendered-page extraction
* dynamic pages where ordinary fetches miss the real UI state
This capability is local-only. The browser bridge runs on the same machine as AI Now and is not exposed through Access Anywhere.
Read the full [Browse Now guide](/docs/browse-now) for setup, limits, and CLI examples.
## Plugins [#plugins]
Extend AI Now with connections to your other apps.
### Custom MCP Servers [#custom-mcp-servers]
Use **AI Now** → **Plugins** → **Add custom MCP** when a tool already exposes an HTTP MCP endpoint. Paste the server URL, add any required headers, enable the plugin, then ask AI Now to use that tool.
For local providers such as Lemonade, use the provider page for chat and add the provider's MCP endpoint separately if you also want AI Now to call its tools. STDIO MCP servers are not yet available in the built-in Rust runtime.
### Built-in Plugins [#built-in-plugins]
#### Obsidian [#obsidian]
1. Go to **AI Now** → **Plugins**
2. Enable **Obsidian**
3. Set your vault path
AI Now can now search and read your Obsidian notes alongside your memories.
#### Notion [#notion]
1. Go to **AI Now** → **Plugins**
2. Enable **Notion**
3. Click **Connect** and authorize in the browser
AI Now can search your Notion pages and databases.
#### Apple Notes (macOS) [#apple-notes-macos]
1. Go to **AI Now** → **Plugins**
2. Enable **Apple Notes**
3. Grant permission when prompted
AI Now can search and read your Apple Notes. No vault path or sync setup needed: it reads directly from the system database. Read-only.
### Custom MCP Plugins [#custom-mcp-plugins]
AI Now supports Model Context Protocol for custom integrations.
### Open Custom Plugins [#open-custom-plugins-step]
Go to **AI Now** → **Plugins** → **Custom Plugins**
### Add MCP Server [#add-mcp-server-step]
Click **Add MCP Server**
### Configure the server [#configure-the-server-step]
Configure the server (stdio command or HTTP endpoint)
### Test the connection [#test-the-connection-step]
Click **Test Connection** to verify
### Enable the plugin [#enable-the-plugin-step]
Enable the plugin
MCP plugins with OAuth (GitHub, Slack, etc.) are detected automatically and prompt for authorization.
## Session Management [#session-management]
Conversations are saved automatically. Click a previous session to resume, or create new sessions for parallel workstreams. Each session maintains its own history.
## Auto-Approve Mode [#auto-approve-mode]
Enable Auto to skip confirmation prompts for file operations and other actions.
Auto-Approve grants AI Now permission to act without asking. Only enable for trusted workflows.
## Using AI Now from Another Device [#using-ai-now-from-another-device]
If your main Nowledge Mem runs on an always-on machine (a Mac Mini, a server, your office desktop), you can use AI Now from any other device that connects via [Access Anywhere](/docs/remote-access).
This is not a separate second knowledge base. You are using the same Mem from another client. If you want the broader model, read [Sync Across Devices](/docs/sync).
How it works:
* Connect from the desktop app, the web app at `/app`, or the mobile app through **Access Anywhere**
* AI Now runs on the Mem server you connected to, using that server's LLM configuration
* Your session list, message history, and pasted images stay with the server, so you can switch clients and continue the same work
* Your memories, threads, and Library are read from the same knowledge base through the secure connection
AI Now is available from connected clients because the agent runs on the Mem server. Keep that server running while you work from another device.
Plugins that read local apps or files, such as Obsidian, Apple Notes, and Browse Now, run on the machine hosting the Mem server. If you connect from a phone or another laptop, those plugins still see the server machine's apps and files.
## Tips [#tips]
* **Be specific**: "What did we decide about the database migration last month?" beats "database stuff"
* **Attach context**: drop files or mention notes with `@` for better results
* **Use sessions**: separate sessions for different projects or topics
## Next Steps [#next-steps]
* **[Access Anywhere](/docs/remote-access)**: Use Mem from any device, the foundation for multi-device workflows
* **[Sync Across Devices](/docs/sync)**: Understand the single-Mem, multi-client sync model
* **[Remote LLM Setup](/docs/usage#remote-llms)**: Configure your AI provider
* **[Connectors](/docs/integrations)**: Connect your AI tools and capture paths
* **[Background Intelligence](/docs/advanced-features)**: How your knowledge grows on its own
# Browse Now (/docs/browse-now)
Browse Now lets Mem use a connected local Chromium browser.
When a page needs your login session, live JavaScript, clicks, forms, or a screenshot, ordinary web fetches are not enough. Browse Now gives AI Now and supported agents a safe local path into your real Chrome, Edge, Arc, or Chromium browser, with the context you already have there.
The Nowledge Mem Exchange extension also supports Firefox for capturing and saving web AI chats. That is a different job. Firefox can use Exchange for capture, Manual Distill, and Thread Backup, but Browse Now browser control uses the Chrome DevTools Protocol and currently requires a Chromium browser.
This is the browser side of Mem. It helps AI Now browse, helps Feed and Timeline agents inspect URLs, and helps the Library learn pages that need a rendered browser instead of a plain download.
Browse Now only controls a browser connected to the same machine as the Mem app or server. Access Anywhere does not expose your browser bridge, and a remote client cannot make the server control the browser on your laptop or phone.
## The First Useful Task [#the-first-useful-task]
If you use AI Now, start with one page that only works in your browser:
1. Open **AI Now**.
2. Go to **Plugins → Skills** and enable **Browse Now**.
3. Ask a task that needs the live page:
> Open my logged-in project dashboard and summarize what changed this week.
You know it is working when the browser opens locally, the agent reads the rendered page, and the answer reflects what is actually visible in that browser session.
If the page is public and static, Mem may use normal web search or URL fetching instead. That is expected. Browse Now is for the cases where a real browser changes the result.
## Where You Will See It [#where-you-will-see-it]
| Place | How Browse Now helps |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| **AI Now** | Lets the agent browse logged-in or dynamic pages during a task. |
| **Feed / Timeline agent** | Gives background agents a way to inspect a URL when page rendering matters. |
| **Library URL learning** | Helps Mem learn pages that require a browser session instead of a plain file download. |
| **External agents** | Provides a CLI and reusable skill so supported agents can operate the browser deliberately. |
Browse Now is not a replacement for memory search. It is the capability Mem uses when the task needs the live web page in front of you.
## Requirements [#requirements]
You need all of these:
* the Nowledge Mem desktop app installed
* the Nowledge Mem Exchange extension installed in Chrome, Edge, Arc, or another supported Chromium browser
* at least one connected browser with the extension active
* for AI Now usage, the **Browse Now** skill enabled in **AI Now → Plugins → Skills**
Firefox is not a Browse Now control browser yet. Use Firefox for Exchange capture; use Chrome, Edge, Arc, or another Chromium browser for Browse Now automation.
If you connect to Mem through Access Anywhere, Browse Now still runs only on the machine hosting the Mem server and its connected browser extension. It does not control the browser on the remote client device.
For normal AI Now, Feed, Timeline, and Library usage, you do not need to run the CLI manually.
## The CLI [#the-cli]
The desktop app also bundles a command-line tool named `browse-now`. Agents use this CLI under the hood, and power users can run it directly.
If the app is installed, the CLI is usually auto-installed for you. Check it with:
```bash
browse-now status
browse-now --help
```
The core loop is:
1. open a page
2. inspect the interactive elements
3. click or fill by reference
4. verify where you landed
5. inspect again after the page changes
Refs such as `@e5` come from `snapshot -i`. They are usually more reliable than guessing a selector or coordinate.
```bash
browse-now open https://example.com
browse-now snapshot -i
browse-now click @e5
browse-now wait 2
browse-now get url
browse-now snapshot -i
```
If the page has weak accessibility data, the CLI also supports text search, text clicks, screenshots, scrolling, key presses, and page-text extraction:
* `browse-now find "query"`
* `browse-now click -T "visible text"`
* `browse-now screenshot /tmp/page.png`
## Useful Commands [#useful-commands]
```bash
browse-now open https://example.com
browse-now snapshot -i
browse-now find "search button"
browse-now click @e12
browse-now fill @e3 "Nowledge Mem" --submit
browse-now get page-text --max-chars 4000
browse-now screenshot /tmp/page.png
```
## What To Ignore At First [#what-to-ignore-at-first]
* You do not need Browse Now for simple public webpages. Normal search or URL learning is faster.
* You do not need the CLI for everyday AI Now usage. Enable the skill and let the agent call it when needed.
* You should not expect it to bypass paywalls, permission prompts, anti-bot checks, or pages your browser itself cannot access.
## External Agent Skill [#external-agent-skill]
There are two common ways to make an agent use `browse-now`:
* in AI Now, enable the built-in **Browse Now** skill
* in external agents, install the reusable `npx skills` package below
If you want supported agents to learn when and how to use `browse-now`, install the reusable skill package from `community`:
```bash
npx skills add nowledge-co/community/nowledge-mem-browse-now-npx-skills
```
That package teaches the agent to:
* prefer `browse-now` for authenticated or interactive browser work
* use refs from `snapshot -i` as the main interaction path
* re-snapshot after navigation
* verify results with `get url` and `get title`
## How It Fits With Mem [#how-it-fits-with-mem]
A strong combined setup looks like this:
* use `Nowledge Mem` skills or integrations to recall context
* use `browse-now` when the task needs the user's real browser
* save durable insights back into Mem when the browser task reveals something worth keeping
## PyPI And Remote Use [#pypi-and-remote-use]
`browse-now` is also published on PyPI. That is for cases where you want the CLI or Python API outside the desktop bundle.
It does **not** mean browser automation becomes a remote-access feature. Even with the PyPI package, the browser bridge still stays on the local machine for security reasons.
## Related Guides [#related-guides]
* [AI Now](/docs/ai-now)
* [Background Intelligence](/docs/advanced-features)
* [Library](/docs/library)
* [Browser Extension](/docs/integrations/browser-extension)
* [Connectors](/docs/integrations)
* [Nowledge Mem CLI](/docs/cli)
# Nowledge Mem CLI (/docs/cli)
The `nmem` CLI gives you terminal access to your Nowledge Mem knowledge base. Search memories, browse threads, read and edit Working Memory, explore the knowledge graph, and view your activity feed, all from the shell.
If you also need browser automation, the desktop app bundles a second CLI called [`browse-now`](/docs/browse-now). It works with the Nowledge Mem Exchange extension to let agents control the user's real browser for authenticated and interactive web tasks. That browser bridge is local-only and is not exposed through Access Anywhere.
## Installation [#installation]
### Option 1: Standalone CLI Package [#option-1-standalone-cli-package]
Install on any machine. Works with a local or remote Nowledge Mem server:
```bash
pip install nmem-cli
# or with uv
uv pip install nmem-cli
# on Arch Linux, use the community-maintained AUR package
yay -S nmem-cli
# or: paru -S nmem-cli
# or run without installing
uvx --from nmem-cli nmem --help
```
**Requirements:** Python 3.11+, Nowledge Mem running locally or reachable remotely.
The standalone package lets you reach your Nowledge Mem from servers, CI/CD pipelines, or remote workstations. See [Access Mem Anywhere](/docs/remote-access). View on [PyPI](https://pypi.org/project/nmem-cli/).
The AUR package is community-maintained by [czyt](https://github.com/czyt) and follows the PyPI `nmem-cli` release. As with any AUR package, review the PKGBUILD before installing.
### Option 2: Bundled with Desktop App [#option-2-bundled-with-desktop-app]
#### macOS [#macos-step]
Go to **Settings → Preferences → Developer Tools** and click **Install CLI**.
Installs to `/usr/local/bin/nmem`.
#### Windows [#windows-step]
The CLI is automatically available after app installation. Open a **new terminal window** to use `nmem`.
#### Linux [#linux-step]
Included with deb/rpm packages. The binary is placed in `/usr/local/bin/nmem`.
***
## Quick Start [#quick-start]
```bash
nmem status # Check connection
nmem ask "What did we decide about deployment?"
nmem ask "What changed?" --space work --ephemeral
nmem m search "project notes" # Search memories
nmem m search "project notes" --space work
nmem m add "Key insight" --title "Learning"
nmem wm # Read today's Working Memory
nmem wm --space work # Read Working Memory for one space
nmem spaces # List known spaces
nmem f --days 1 # Today's activity
nmem g expand # Explore graph connections
nmem tui # Interactive terminal UI
```
***
## Global Options [#global-options]
| Option | Description |
| ----------------- | -------------------------------------------------------------------------- |
| `-j, --json` | Machine-readable JSON output |
| `--api-url ` | API URL (default: `http://127.0.0.1:14242`) |
| `--space ` | Run the command inside one named space when you want a non-default context |
| `-v, --version` | Show version |
| `-h, --help` | Show help |
**Aliases:** `m` = memories · `t` = threads · `wm` = working-memory · `g` = graph · `f` = feed · `c` = communities
***
## Ask your knowledge (`nmem ask`) [#ask-your-knowledge-nmem-ask]
Ask across Memories, past conversations, Library documents, and graph
connections from the terminal:
```bash
nmem ask "What did we decide about the authentication migration?"
nmem ask "Summarize the evidence" --space "Research"
nmem ask "Is this documented anywhere?" --ephemeral
nmem --json ask "Which sources support this decision?"
```
By default, the question and completed answer are saved to Timeline so you can
reopen the evidence or continue the conversation later. Use `--ephemeral` for a
one-off answer that should not create a Timeline entry. Progress is written to
stderr and the answer to stdout, so ordinary shell piping stays clean;
`--json` returns one terminal object with the answer, evidence references,
retrieval coverage, and Timeline event ID.
`--space` follows that Space's normal strict/shared/all retrieval policy. It
does not bypass Space boundaries.
***
## Memory Commands (`nmem m`) [#memory-commands-nmem-m]
If you do not use spaces, ignore `--space` and keep working in the default space. When you do need separate project or agent contexts, the same commands work with `--space ""`.
### List memories [#list-memories]
```bash
nmem m # Recent 10 memories
nmem m -n 50 # List 50
nmem m --importance 0.7 # Minimum importance filter
```
### Search [#search]
```bash
nmem m search "authentication patterns"
nmem m search "authentication patterns" --space work
nmem m search "API design" --importance 0.8
nmem m search "deploy" -l devops -l backend # Filter by labels (AND)
nmem m search "renewal" --metadata customer=acme --metadata purpose=contract-review
nmem m search "sprint" --mode deep # Graph + LLM-enhanced results
nmem m search "old deployment notes" --include-history
```
Search shows where a memory came from and how old it is in the default table. By default, recall returns current memories only; memories that were superseded by a newer version stay in graph history but do not keep competing in normal search. Use `--include-history` when you are auditing how an answer changed over time.
Use `--metadata key=value` for stable fields your workflow already knows, such as
customer, project, material type, or purpose. Repeat `--metadata` to narrow the
memory set before ranking.
**Bi-temporal search.** Distinguish *when something happened* from *when you saved it*:
```bash
nmem m search "database decision" --event-from 2025-01 --event-to 2025-06
nmem m search "meeting notes" --recorded-from 2026-01-01
```
| Option | Description |
| -------------------- | --------------------------------------------------------- |
| `-n` | Max results |
| `-l, --label` | Filter by label (repeatable) |
| `--metadata, --meta` | Filter by memory metadata key/value (repeatable) |
| `--importance` | Minimum importance (0–1) |
| `--mode` | `normal` (default, fast) or `deep` (graph + LLM-enhanced) |
| `--include-history` | Include superseded/deprecated memory versions |
| `--event-from/to` | When the fact *happened* (YYYY, YYYY-MM, or YYYY-MM-DD) |
| `--recorded-from/to` | When it was *saved* to Nowledge Mem (YYYY-MM-DD) |
### Add [#add]
```bash
nmem m add "We chose PostgreSQL for task events"
nmem m add "Prefer functional components in React" \
--title "Frontend conventions" \
--unit-type preference \
--importance 0.8 \
-l frontend -l react
# Record when something actually happened (bi-temporal)
nmem m add "Decided to sunset the legacy API" \
--unit-type decision \
--event-start 2025-11 \
--when past
# Preserve provenance when an agent distills a thread
nmem m add "The migration script must run after the schema check" \
--unit-type learning \
--source claude-code \
--source-thread thread_abc \
--source-msg msg_042
```
| Option | Description |
| ------------------ | ------------------------------------------------------------------------------ |
| `-t, --title` | Memory title |
| `-i, --importance` | Importance 0–1 |
| `-l, --label` | Add label (repeatable) |
| `--unit-type` | `fact` `preference` `decision` `plan` `procedure` `learning` `context` `event` |
| `--event-start` | When it happened (YYYY, YYYY-MM, YYYY-MM-DD) |
| `--event-end` | End of a time range |
| `--when` | `past` `present` `future` `timeless` (default: timeless) |
| `--source-thread` | Thread ID this memory was distilled from |
| `--source-msg` | Message ID this memory was distilled from |
| `--source-range` | Message index range, for example `12:18` |
### Review memory types [#review-memory-types]
Use this when old or weakly typed memories should be reviewed against the current type system. The command defaults to a dry run. Applying changes updates only memory metadata and search-index filter metadata; it does not rewrite memory content, re-embed memories, or rebuild the search index.
```bash
nmem m reclassify-types
nmem m reclassify-types --target-type procedure
nmem m reclassify-types --unit-type learning --unit-type decision --target-type procedure
nmem --json m reclassify-types --target-type procedure --wait
nmem m reclassify-types --apply --target-type procedure --limit 50
```
Use `--target-type procedure` when you are repairing reusable how-tos that were previously saved as decisions or learnings. Use `--wait` when a script wants the Feed result for the exact review request before continuing.
### Show [#show]
```bash
nmem m show
nmem m show --content-limit 500
```
### Update [#update]
```bash
nmem m update --title "New title"
nmem m update --importance 0.9
nmem m update --content "Updated content"
```
### Deprecate or supersede [#deprecate-or-supersede]
Use lifecycle commands when a memory is no longer true. This keeps the old memory available for history while removing it from normal recall.
```bash
nmem m deprecate mem_old --reason "The API changed"
nmem m supersede mem_old mem_new --reason "The newer deployment decision replaced it"
```
`supersede` is not a delete. It records an EVOLVES `replaces` link from the old memory to the new memory, moves labels forward to the replacement, and leaves the older memory available through history views and `m search --include-history`.
### Move between spaces [#move-between-spaces]
Use this when you already saved memories in one space and want to move them into another one.
```bash
nmem m move --space "Research Agent" --to-space "Archive"
nmem m move --space "Research Agent" --to-space "Archive" -f
nmem m move --all-in-space "Research Agent" --to-space "Archive" --dry-run
nmem m move --all-in-space "Research Agent" --to-space "Archive" -f
```
`--space` is the source space. `--to-space` is the destination. For whole-space moves, use `--dry-run` first if you want to preview the count before changing anything.
### Delete [#delete]
```bash
nmem m delete
nmem m delete -f # Skip confirmation
nmem m delete # Multiple IDs
```
`nmem m delete` is interactive by default. For scripts, agents, CI, or any non-interactive shell, use `-f` so the command does not block waiting for confirmation.
***
## Thread Commands (`nmem t`) [#thread-commands-nmem-t]
### List and search [#list-and-search]
```bash
nmem t # Recent threads
nmem t list --source openclaw -n 20 # Recent OpenClaw threads only
nmem t list --offset 20 -n 20 # Next page of recent threads
nmem t search "architecture decisions"
```
Use `list` when you want the newest threads in order. Use `search` when you want full-text matches inside thread content.
### Show [#show-1]
```bash
nmem t show
nmem t show -n 50 # Show up to 50 messages
nmem t show --content-limit 200
```
### Create [#create]
```bash
# From text
nmem t create -t "Quick note" -c "Remember to review the API changes"
# From a file
nmem t create -t "Meeting notes" -f notes.md
# With structured messages
nmem t create -t "Chat session" \
-m '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi!"}]'
# With a stable ID (idempotent, safe to re-run)
nmem t create -t "OpenClaw session" --id "openclaw-abc123-session"
```
### Append [#append]
Add messages to an existing thread. Safely idempotent: duplicate messages are filtered by content hash or external ID.
```bash
# Single message
nmem t append -c "Follow-up note"
# Structured messages
nmem t append \
-m '[{"role":"user","content":"Question"},{"role":"assistant","content":"Answer"}]'
# With idempotency key (safe for retries / repeated hook fires)
nmem t append \
-m '[{"role":"user","content":"msg"}]' \
--idempotency-key "oc-batch-session-001"
```
### Save Claude Code / Grok Build / Codex / Gemini CLI session [#save-claude-code--grok-build--codex--gemini-cli-session]
```bash
nmem t save --from claude-code # Save Claude Code session
nmem t save --from grok # Save Grok Build session
nmem t save --from codex # Save Codex session
nmem t save --from codex -s "Summary" # With session summary
nmem t save --from gemini-cli # Save Gemini CLI session
```
By default, `nmem` reads Claude Code from `~/.claude`, Grok Build from `~/.grok`, and Codex from `~/.codex`. If you keep those tools in a custom location, `CLAUDE_CONFIG_DIR`, `GROK_HOME`, and `CODEX_HOME` are respected automatically.
| Option | Description |
| --------------- | ---------------------------------------------------------- |
| `--from` | `claude-code`, `grok`, `codex`, or `gemini-cli` (required) |
| `-p, --project` | Project directory path (default: current dir) |
| `-m, --mode` | `current` (latest) or `all` sessions |
| `--session-id` | Specific session ID (Codex and Grok Build) |
| `-s, --summary` | Brief session summary |
| `--truncate` | Truncate large tool results (>10KB) |
### Delete [#delete-1]
```bash
nmem t delete
nmem t delete -f # Force
nmem t delete --cascade # Also delete associated memories
```
### Move between spaces [#move-between-spaces-1]
```bash
nmem t move --space "Research Agent" --to-space "Archive"
nmem t move --space "Research Agent" --to-space "Archive" -f
nmem t move --all-in-space "Research Agent" --to-space "Archive" --dry-run
nmem t move --all-in-space "Research Agent" --to-space "Archive" -f
```
As with memories, `--space` is the source guard and `--to-space` is the destination. Mem resolves whole-space moves on the server, so scripts do not need to page through every result first.
***
## Nowledge FS (`nmem fs`) [#nowledge-fs-nmem-fs]
`nmem fs` is the CLI for **Nowledge FS**, the preview path-first layer that powers [Knowledge Tree](/docs/nowledge-fs). Use it when a script or agent should navigate Mem as paths instead of juggling separate memory, thread, wiki, feed, and Library commands.
This is a preview shape, not a local mount yet. The paths are stable Mem identifiers served by the Mem API, so they work from the desktop app, the web client, remote clients, scripts, and MCP-connected agents.
```bash
nmem fs capabilities --json # Discover roots, verbs, and limits
nmem fs ls / # Top-level branches
nmem fs cat /wiki/entities/PostgreSQL.entity.md
nmem fs cat /sources/research-report-abc123.pdf --line 120 --lines 80
nmem fs stat /memories/by-id/mem_abc.memory.md
nmem fs find /memories --label decisions --since 2026-01-01
nmem fs grep "JWT rotation" /memories
nmem fs grep "JWT rotation" /threads
nmem fs grep "JWT rotation" /sources
nmem fs grep -E "JWT|token" /threads --jsonl
nmem fs grep "JWT rotation" /threads --jsonl
nmem fs recall "session token strategy" --in /memories
```
Use `capabilities --json` when a script or adapter needs the current root list, supported verbs, limits, or feature flags. Use `recall` when wording is fuzzy and you are looking for memories, `find` when the constraint is structural, and `grep` when you need an exact phrase. `grep` is case-insensitive by default; add `--case-sensitive` for exact casing or `-E` for regex patterns such as `JWT|token`. Results are paths, so you can pipe or copy them into `cat`. `grep` also returns line numbers; use `cat --line` and `--lines` to inspect just the useful window of a long thread or parsed document.
```bash
nmem fs recall "why did we change token refresh?" --in /memories -k 5 --paths \
| while IFS= read -r kfs_path; do nmem fs cat "$kfs_path"; done
nmem fs grep "JWT rotation" /threads --jsonl \
| while IFS= read -r hit; do
kfs_path=$(printf '%s' "$hit" | jq -r '.path')
kfs_line=$(printf '%s' "$hit" | jq -r '.line')
nmem fs cat "$kfs_path" --line "$kfs_line" --lines 12
done
```
Start broad, then narrow: `recall` or `find` returns paths, `ls` gives nearby context, `stat` checks metadata cheaply, and `cat` loads only the final object. This keeps context small while preserving the user's mental model of a tree.
Canonical writable paths can be updated from the shell:
```bash
cat note.md | nmem fs write /memories/by-id/mem_abc.memory.md --stdin
nmem fs rm /memories/by-id/mem_abc.memory.md --force
```
Alias and derived paths stay read-only. For example, a memory shown under a label or date branch should be edited through its `/memories/by-id/...` path.
### Verbs [#verbs]
| Verb | Use it for |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `capabilities` | Discover supported roots, verbs, limits, and feature flags. Use `--json` for scripts. |
| `ls PATH` | List a branch. Use `--cursor` with `-n` when a directory is paginated. |
| `cat PATH` | Read a rendered object body plus frontmatter. Add `--line N --lines M` for a small window. |
| `stat PATH` | Inspect metadata without loading the body. |
| `find PATH ...` | Structural search, such as `--type memory`, `--label decisions`, `--since 2026-01-01`, or `--mentions PostgreSQL`. |
| `grep QUERY PATH` | Exact-string search over memories, thread messages, and parsed Library documents. Add `-E` for regex. |
| `recall QUERY --in /memories` | Semantic memory search that returns paths. |
| `write PATH` | Update a canonical writable object. |
| `rm PATH` | Delete a canonical writable object. |
For shell pipelines, `find`, `grep`, and `recall` support `--paths`; `grep` also supports `--jsonl` when the next command needs both `path` and `line`. In `zsh`, avoid naming loop variables `path`; it shadows the shell's command search path.
### Current boundaries [#current-boundaries]
* `nmem fs` is API-backed. It does not create a real folder on disk yet.
* The preview release supports Tree, `/fs/*`, CLI, and MCP. Mounting is planned for a later phase.
* `grep` is exact-string search. It can search memories, thread messages, and parsed Library documents. It is case-insensitive by default; use `--case-sensitive` for exact casing or `-E` for regex. Use `recall` for semantic memory search.
* Source fragments such as PDF pages or spreadsheet sheets, plus SQL/Cypher/replay/tail, are planned after their schemas and safety limits are pinned.
* Errors use familiar filesystem-style codes: `ENOENT` for missing paths, `EROFS` for derived read-only paths, `EXDEV` for alias write attempts, and `ENOTSUP` for verbs that are designed but not shipped yet.
***
## Library Sources (`nmem sources`) [#library-sources-nmem-sources]
Your [Library](/docs/library) (PDFs, spreadsheets, Word files, presentations, Markdown, code, and URLs) is reachable from the terminal. Use `nmem sources` when a script needs to find a document, read a passage from it, or pull structured analysis out of a spreadsheet without opening the app.
`nmem sources` aliases to `nmem s`.
### List, add, show, delete [#list-add-show-delete]
```bash
nmem sources list # Sources in the current space
nmem sources add notes.pdf # Import a file
nmem sources add https://example.com/doc # Capture a URL
nmem sources show src_abc123 # Metadata for one source
nmem sources delete src_abc123 -f # Delete (non-interactive)
```
### Search across the Library [#search-across-the-library]
```bash
nmem sources search "meeting notes"
nmem sources search roadmap -n 10
nmem sources search "renewal terms" --label customer-acme --metadata purpose=contract-review
nmem sources list --metadata material_type=case-study
```
Full-text match against filenames and parsed summaries. Returns source IDs you can feed into the commands below.
Use `--label` for broad source labels and `--metadata key=value` for fields your import flow already knows, such as customer, project, material type, or purpose. Repeat `--label` or `--metadata` to narrow the result set before ranking.
### Read parsed content [#read-parsed-content]
```bash
nmem sources read src_abc123 # First 8000 characters
nmem sources read src_abc123 --offset 8000 # Next page
nmem sources read src_abc123 --limit 16000 # Larger window
```
Returns the parsed text of one document, paged by character offset. Useful for feeding a specific section into another tool.
### Search inside a single document [#search-inside-a-single-document]
```bash
nmem sources search-chunks src_abc123 "risk factors"
nmem sources search-chunks src_abc123 budget -n 3
```
Runs a full-text search against the indexed chunks of one source. Each match comes back with the actual passage, chunk index, and score, so you and any downstream agent can see what was matched, not just how many chunks matched.
### Analyze tabular sources [#analyze-tabular-sources]
```bash
nmem sources analyze src_abc123 # All columns
nmem sources analyze src_abc123 --column price --column region # Specific columns
```
Runs structured analysis on CSV, TSV, XLSX, or XLS sources: column stats, distributions, and basic shape. For narrative documents, use `search-chunks` and `read` instead.
`search`, `read`, `search-chunks`, and `analyze` are the same Library tools available to AI Now, the Feed Agent, the Graph Intelligence Agent, and MCP-connected clients. Anything you can do from the terminal, agents can do on your behalf, and vice versa.
***
## Working Memory (`nmem wm`) [#working-memory-nmem-wm]
Working Memory is the AI-generated daily briefing: focus areas, open questions, and recent activity. Background Intelligence updates it each morning.
The **Default** space keeps the familiar compatibility file at `~/ai-now/memory.md`. If spaces are enabled, `nmem wm` can read or edit the briefing for any space with `--space ""`.
### Read [#read]
```bash
nmem wm # Today's Working Memory
nmem wm --space work # Working Memory for one space
nmem wm --date 2026-02-12 # Archived date
nmem wm history # List available archived dates
```
### Edit [#edit]
```bash
nmem wm edit # Opens $EDITOR
nmem wm edit --space work # Edit one space
nmem wm edit -m "## Focus Areas\n- Ship v0.6" # Set directly
```
### Patch a section (non-destructive) [#patch-a-section-non-destructive]
Replace or append to one section without touching the rest of the document:
```bash
# Replace a section
nmem wm patch --heading "## Focus Areas" --content "- Finish OpenClaw plugin release"
# Append to a section
nmem wm patch --heading "## Notes" --append "Reminder: deploy to staging tonight"
```
The heading is matched case-insensitively and partially. `"Focus"` matches `"## Focus Areas"`.
## Spaces (`nmem spaces`) [#spaces-nmem-spaces]
Use this only when you want more than the default space.
```bash
nmem spaces
nmem spaces create "Research Agent"
nmem spaces update "Research Agent" --instructions "Prefer research notes and hypotheses"
nmem spaces show "Research Agent"
```
If you need a stable storage key for automation, `--id` is still available as an advanced option. Most people should let Mem generate it.
***
## Graph Commands (`nmem g`) [#graph-commands-nmem-g]
### Expand graph neighborhood [#expand-graph-neighborhood]
Explore connected memories, entities, crystals, and source documents around a given memory:
```bash
nmem g expand
nmem g expand --depth 2 # Two hops out
nmem g expand -n 10 # Limit neighbors per hop
```
### Show EVOLVES version chain [#show-evolves-version-chain]
See how a memory has been refined or superseded over time:
```bash
nmem g evolves
```
***
## Feed (`nmem f`) [#feed-nmem-f]
The activity feed shows what was saved, learned, synthesized, or ingested, in chronological order.
```bash
nmem f # Last 7 days (high-signal events)
nmem f --days 1 # Today only
nmem f --days 30 # Last 30 days
nmem f --type crystal_created # Only crystal synthesis events
nmem f --from 2026-02-10 --to 2026-02-14 # Exact date range
nmem f --all # Include low-signal background events
nmem f -n 50 # Limit events (default: 100)
```
| Option | Description |
| ---------------- | ------------------------------------------------ |
| `--days` | How many days back (default: 7; use 1 for today) |
| `--type` | Filter by event type |
| `-n, --limit` | Max events to fetch (default: 100) |
| `--all` | Include low-signal background events |
| `--from`, `--to` | Exact date range (YYYY-MM-DD) |
**Event types:** `memory_created` · `crystal_created` · `insight_generated` · `source_ingested` · `source_extracted` · `daily_briefing` · `url_captured`
***
## Knowledge Communities (`nmem c`) [#knowledge-communities-nmem-c]
Browse topic clusters automatically detected in your knowledge graph:
```bash
nmem c # List communities
nmem c -n 20
nmem c show # Show community details (entities, memories)
nmem c detect # Trigger community detection (background)
```
***
## Configuration & Models [#configuration--models]
### Search Index Model [#search-index-model]
```bash
nmem models status # Check current model status
nmem models download # Download the Search Index Model
nmem models reindex # Rebuild the search index
```
### LLM provider [#llm-provider]
```bash
nmem config provider list
nmem config provider set openai --api-key sk-xxx --model gpt-4o
nmem config provider test
```
### Processing settings [#processing-settings]
```bash
nmem config settings # Show all settings
nmem config settings set briefingHour 8 # Change morning briefing time
```
### Client connection settings [#client-connection-settings]
Use this when the current machine needs to connect to a remote Mem server:
```bash
nmem config client show
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_...
nmem config client clear api-key
```
`nmem config client ...` updates the local client config used by this machine's CLI and plugins. It is separate from `nmem config access ...`, which controls how a Mem server is exposed to other devices.
### MCP config snippets [#mcp-config-snippets]
Use this when an AI host or orchestrator asks for an MCP config file instead of reading the Mem client config directly:
```bash
nmem config mcp show --host claude-code
nmem config mcp show --host codex
nmem config mcp show --host cursor
nmem config mcp show --host gemini-cli
```
The snippet includes the resolved Mem URL, API key headers when configured, and the right shape for that host. If another tool launches Claude Code for you, that launcher still needs to pass Claude Code the generated MCP config.
### License [#license]
```bash
nmem license status
nmem license activate [email] # Email is inferred from the license key when possible
nmem license renew # Refresh or renew this device's authorization
nmem license deactivate # Deactivate license on this device
```
***
## Remote Access [#remote-access]
```bash
# LAN / private network
export NMEM_API_URL=http://192.168.1.100:14242
nmem status
# Cloudflare tunnel (from desktop app: Settings → Access Mem Anywhere)
export NMEM_API_URL=https://
export NMEM_API_KEY=nmem_...
nmem m search "notes"
# One-off without env vars
nmem --api-url https:// status
```
| Variable | Description | Default |
| -------------- | --------------------- | ------------------------ |
| `NMEM_API_URL` | API server URL | `http://127.0.0.1:14242` |
| `NMEM_API_KEY` | API key (Bearer auth) | *(unset)* |
Full guide: [Access Mem Anywhere](/docs/remote-access).
***
## JSON Output [#json-output]
Add `--json` (or `-j`) before the subcommand for machine-readable output:
```bash
nmem --json m search "API design" | jq '.memories[0].id'
nmem --json m add "Note" | jq -r '.id'
nmem --json f --days 1 | jq '.events[].title'
```
### Search response [#search-response]
```json
{
"query": "API design",
"total": 3,
"search_mode": "fast_bm25_vector",
"memories": [
{
"id": "abc123-def456-...",
"title": "REST API versioning decision",
"content": "We use /v1/ prefix for all public endpoints...",
"score": 0.91,
"relevance_reason": "Text Match (89%) + Semantic Match (73%) | decay[imp:high]",
"importance": 0.8,
"labels": ["architecture", "api"],
"event_start": "2025-09",
"temporal_context": "past",
"source": "cli"
}
]
}
```
### Feed response [#feed-response]
```json
{
"events": [
{
"id": "evt-...",
"event_type": "memory_created",
"severity": "info",
"title": "Memory or event title",
"description": "Summary text...",
"metadata": { "source": "claude", "unit_type": "fact" },
"related_memory_ids": ["..."],
"created_at": "2026-02-20T02:35:28+00:00"
}
]
}
```
### Error response [#error-response]
```json
{
"error": "api_error",
"status_code": 404,
"detail": "Memory not found"
}
```
***
## Status and Statistics [#status-and-statistics]
```bash
nmem status
# nmem v0.6.2
# status ok
# api http://127.0.0.1:14242
# database connected
# search ready
nmem stats
# Database Statistics
# memories 83
# threads 27
# entities 248
# labels 177
# communities 32
```
If search needs attention, `nmem status` tells you which case you are in:
* `search rebuild needed`: run `nmem models reindex`
* `search updating metadata`: Mem is filling new search metadata in the background. No rebuild is needed.
***
## AI Agent Integration [#ai-agent-integration]
The `--json` flag and stable exit codes make `nmem` easy to drive from AI agents.
```bash
# Search for context before responding
nmem --json m search "authentication flow" | jq '.memories[:3]'
# Save an insight
nmem m add "Rate limiting is per-user, not per-IP" \
--unit-type learning --importance 0.8 -l backend
# Save a decision with when it was made
nmem m add "Chose Postgres over MySQL for task events" \
--unit-type decision --event-start 2026-02 -l architecture
# Browse what was worked on last week
nmem --json f --days 7 | jq '.events[].title'
# Create a session thread backup
nmem t create -t "Debug session $(date +%Y%m%d)" \
-m '[{"role":"user","content":"Investigate auth failures"},{"role":"assistant","content":"Found rate limit issue"}]'
```
***
## TUI [#tui]
An interactive terminal UI for browsing memories, threads, and the knowledge graph:
```bash
nmem tui
```
If you launch the TUI with `NMEM_SPACE="Research Agent"`, the Memories and Threads tabs stay inside that space. This is useful for agent workstations or terminal-only servers where one shell session belongs to one project or agent lane.
For moving many records between spaces, use the app or the `nmem m move` / `nmem t move` commands. The TUI keeps browsing and editing scoped, but it does not add a separate multi-select move workflow.
In the `Settings` tab, you can also manage **Access Anywhere** (Quick link / stable Cloudflare account mode) from terminal-only environments. This is the same remote-access feature documented in [Access Mem Anywhere](/docs/remote-access).
***
## Troubleshooting [#troubleshooting]
**"command not found: nmem"**
* PyPI install: `pip install nmem-cli` (Python 3.11+)
* Arch Linux: `yay -S nmem-cli` or `paru -S nmem-cli`
* Run without installing: `uvx --from nmem-cli nmem --help`
* macOS desktop: Settings → Preferences → Developer Tools → Install CLI
* Windows: open a new terminal after app installation
**"Cannot connect to server"**
1. Ensure Nowledge Mem is running
2. Try: `nmem --api-url http://127.0.0.1:14242 status`
3. Check for proxy or VPN blocking localhost
# Community & Support (/docs/community)
## Community Channels [#community-channels]
## Get Support [#get-support]
Choose the fastest path for the kind of help you need:
* **Discord** for setup questions, workflow advice, and quick product help
* **GitHub Issues** for bugs, feature requests, and reproducible product problems
* **Email / private channels** when you need account or sensitive support
### Documentation [#documentation]
* **[Getting Started](/docs/getting-started)**: Your first five minutes with the Timeline and your first saved knowledge
* **[Connectors](/docs/integrations)**: Choose the right connection path for each AI tool
* **[Background Intelligence](/docs/advanced-features)**: Knowledge graph, insights, crystals, and working memory
* **[Troubleshooting](/docs/troubleshooting)**: Common issues and solutions
### Report Issues & Request Features [#report-issues--request-features]
Licensed users may have access to higher-touch support channels depending on their purchase and rollout status. If you need help and are not sure which channel applies, start with email or Discord.
# Back Up, Export, and Import (/docs/data-portability)
Nowledge Mem is local-first. Data Transfer is how you keep that promise practical: you can export your knowledge, store it yourself, and import it into another Mem when you need to move.
Use it when you want a backup before a major change, a one-time migration to another machine, or an offline copy you can inspect later.
The Mem export itself is not an opaque binary database dump. It is a text-based bundle: JSON manifest files, JSONL records for memories, threads, sources, entities, skills, and graph edges, non-secret AI Profiles and Rules, plus Markdown for Working Memory. If you choose to include original Library files or managed skill bundles, those files keep their original format. The `.zip` is only packaging.
## When To Use Data Transfer [#when-to-use-data-transfer]
Use **Settings -> Data Transfer** when you want to:
* back up your knowledge before reinstalling or upgrading
* move from one computer to another
* move between desktop, Linux server, and headless deployments
* keep a human-inspectable archive of your Mem data
* keep reusable skills with the knowledge they were created from
* import a previous export into a fresh Mem install
This is different from [Sync Across Devices](/docs/sync). Sync means one always-on Mem with many clients connected to it. Data Transfer is for backup, export, import, and one-time migration.
It is also different from the [Open Knowledge Format (OKF)](/docs/concepts/open-knowledge-format) export. Data Transfer is a complete, re-importable backup of your Mem; the OKF export is a portable, readable knowledge bundle for handing your knowledge to other tools.
## Data Transfer vs Search Maintenance [#data-transfer-vs-search-maintenance]
Use **Data Transfer** when you need a copy of your knowledge or want to move it somewhere else.
Use **Settings -> Memory Processing -> Search** for local maintenance:
* **Optimize** compacts the rebuildable search index when it is using too much disk space.
* **Rebuild Index** recreates search from your saved memories, library content, and message store when results look stale or incomplete.
Neither action creates a backup. They also do not replace export/import. If you are preparing for a major upgrade or moving to another machine, export first.
## Export From The App [#export-from-the-app]
1. Open **Settings**.
2. Go to **Data Transfer**.
3. Choose what to include.
4. Keep **Compress as .zip** on if you want a single file.
5. Click **Export**.
On desktop, you can export either a `.zip` file or an expanded folder. In web or remote client mode, the browser downloads a `.zip` because the client cannot write directly to the server's filesystem.
A successful export gives you a `.zip` file or folder containing a `manifest.json` file. Keep that file somewhere you control: external drive, encrypted backup, NAS, or your normal backup system.
## Import Into Another Mem [#import-into-another-mem]
1. Open **Settings -> Data Transfer** on the destination Mem.
2. Pick an import mode.
3. Select the export `.zip` or folder.
4. Start the import and wait for it to finish.
5. Check Timeline, Library, Search, and the Knowledge Graph.
Import runs as a background job. Large exports can take time because Mem needs to restore records and rebuild search projections.
## Import Modes [#import-modes]
Choose the mode based on what should happen when the export contains an item that already exists on the destination.
| Mode | Best For | What It Does |
| ------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Merge** | Normal restores and migrations | Keeps existing records and fills in missing related data where possible. |
| **Skip** | Importing an archive into an active Mem | Leaves destination records untouched when the same item already exists. |
| **Overwrite** | Replacing a test or stale destination | Replaces matching records with the export copy. Use this only when the export should win. |
If you are not sure, start with **Merge**.
## What Is Inside The Export [#what-is-inside-the-export]
The exact contents depend on the options you choose, but a Mem export can include:
| Path | Purpose |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `manifest.json` | Export format, version, counts, and included sections. |
| `nodes/*.jsonl` | Memories, threads, sources, entities, labels, communities, and other graph nodes. |
| `relationships/*.jsonl` | Graph relationships between those nodes. |
| `content_store/*.jsonl` | Thread messages and larger content payloads when included. This is the portable form of Mem's message store. |
| `working_memory.md` | Current Working Memory in Markdown. |
| `working_memory_archive/` | Archived Working Memory snapshots, when included. |
| `skills/` | Managed skill bundles, including `SKILL.md` and bundled files. |
| `settings/*.json` | Non-secret AI Profiles and Rules, so named agents keep their identity and behavior after migration. |
| original source files | Optional Library files, kept in their original format. |
This format is meant to be recoverable and inspectable. You are not locked into a hidden desktop-only database file.
## What This Does Not Move [#what-this-does-not-move]
Data Transfer is for your knowledge data. It is not a full clone of the whole app install.
After moving to a new machine, you may still need to reconnect model providers, integrations, remote-access settings, licenses, or operating-system-level app preferences. AI Profiles and Rules are included, but API keys, provider credentials, and license tokens are not.
Search indexes, embeddings, and active skill projection folders are not moved as source data. Mem rebuilds those projections from the restored memories, messages, Library files, and managed skill bundles.
Background task queues, in-progress catch-up plans, and the local AI usage ledger are also not moved. After import, the new Mem recalculates maintenance backlog from the restored memories. If the old Mem was still catching up, start catch-up again on the new machine.
For a self-hosted Docker or Linux server, also read [Server Deployment](/docs/server-deployment). Server operators can choose between a fast volume-level snapshot and an application-level export that uses the same portable Mem data format.
If you are automating the same flow, the API reference includes [export](/docs/api/data/export/post), [download export](/docs/api/data/export/download/post), [import](/docs/api/data/import/post), and [upload import](/docs/api/data/import/upload/post) endpoints.
For large browser/API downloads, Mem stages the temporary export files on its app storage volume instead of the container's small `/tmp` area. Keep enough free space on the Mem data/config volume for the export workspace and the final `.zip`; Mem will not overwrite an existing export file unless you explicitly enable overwrite.
## Good Backup Habits [#good-backup-habits]
* Export before a major upgrade or machine migration.
* Keep at least one recent export outside the computer that runs Mem.
* Use `.zip` when you want a single portable file.
* Use a folder export on desktop when you want to inspect the files directly.
* Test an import into a spare Mem before deleting the original machine.
Your knowledge should be yours. Data Transfer is the practical way to keep that true.
# Docker Deployment (/docs/docker)
**Not sure if you need this?** Most people use Nowledge Mem as a desktop app on macOS, Windows, or Linux. Install once, the data lives locally, no Linux or Docker knowledge required. See **[Installation](/docs/installation)**.
This page is for the specific case where you want Mem to run as a **headless server** on a host you administer, such as a VPS, a home NAS, a cloud VM, or a homelab box, so the web app and `nmem` CLI on your other devices can reach it over your network.
The official `nowledgelabs/mem` image runs the same backend as the desktop app, serves the web app at `/app`, and keeps all your data in three plain bind-mounted directories on the host (`./data`, `./config`, `./cache`). You back them up with whatever you already use: `rsync`, `restic`, `tar`, ZFS snapshots.
It is in preview: shipping and verified end-to-end on real hosts, but the operator surface will keep evolving while we round it out.
## Is this path for you? [#is-this-path-for-you]
Pick Docker when **all** of these are true:
* You have a long-running host you administer, such as a VPS, a home NAS box, a cloud VM, or a homelab server, and you want Mem to live there as a service.
* You already manage other long-running services with Docker on that host, or you're comfortable enough with a shell to run a few commands and edit a `compose.yaml`.
* You want one centralized Mem server that the web app and the `nmem` CLI on your laptop / phone / other machines can connect to over your network.
If none of those fit, install the **[desktop app](/docs/installation)** instead. That is the normal path for almost every user, and your data still lives entirely on your machine.
## Supported architectures [#supported-architectures]
The image is published as a multi-arch manifest, so `docker pull nowledgelabs/mem:` resolves correctly on the two architectures you'll typically run a server on:
| Architecture | Where it usually runs |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| `linux/amd64` | Standard x86\_64 VPS, cloud VMs, x86 NAS boxes (Synology DSx+, QNAP TS-x73AU, etc.), homelab servers |
| `linux/arm64` | Ampere / AWS Graviton VPS, arm64 NAS boxes, Raspberry Pi 5 class boards |
You don't pick the arch; Docker pulls the right one for the host. If you happen to run Docker Desktop on an Apple Silicon Mac for development, it'll pull `arm64` and work, but that isn't the recommended path: on a personal Mac, the desktop app is simpler.
## GPU image (optional) [#gpu-image-optional]
If your host has an NVIDIA GPU and you want faster local embeddings, run the opt-in `:-cuda` tag instead of the default:
```bash
docker run --gpus all ... nowledgelabs/mem:-cuda
```
In the compose stack, point the `mem` service `image:` at the `:-cuda` tag and add `gpus: all` (Compose v2.30+) or the equivalent `deploy.resources` reservation.
A few things worth knowing before you switch:
* The GPU image is `linux/amd64` only. The default `:` tag stays multi-arch (`amd64` + `arm64`) and CPU-only, so keep using it unless you specifically want GPU acceleration.
* The host needs the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) installed. Without it the container still starts, but it falls back to CPU, so you gain nothing.
* The image bundles the GPU-accelerated embedding runtime, not a language model. You still supply your own GGUF model the same way you would on the CPU image.
Everything else on this page (data layout, backups, upgrades, verification) is identical for both tags.
## GPU image for AMD and Intel (Vulkan) [#gpu-image-for-amd-and-intel-vulkan]
If your host has an AMD or Intel GPU, run the `:-vulkan` tag. It uses Vulkan, so it also works on NVIDIA, though the `:-cuda` image is usually faster there.
For AMD or Intel, pass the GPU's render node. No extra toolkit is needed:
```bash
docker run --device /dev/dri -p 14242:14242 ... nowledgelabs/mem:-vulkan
```
For NVIDIA on this image, use the NVIDIA Container Toolkit with the graphics capability instead:
```bash
docker run --gpus all -e NVIDIA_DRIVER_CAPABILITIES=graphics,compute,utility \
-p 14242:14242 ... nowledgelabs/mem:-vulkan
```
In the compose stack, point the `mem` service `image:` at the `:-vulkan` tag and add the matching device passthrough (`devices: ["/dev/dri:/dev/dri"]` for AMD or Intel).
A few things worth knowing before you switch:
* This image is `linux/amd64` only. The default `:` tag stays multi-arch (`amd64` + `arm64`) and CPU-only, so keep using it unless you specifically want GPU acceleration.
* If no Vulkan device is visible, the container still starts and falls back to CPU, so it's safe to run without a GPU, just slower.
* Like the CUDA image, it bundles the GPU-accelerated runtime, not a language model. You still supply your own GGUF model the same way you would on the CPU image.
Everything else on this page (data layout, backups, upgrades, verification) is identical for all three tags.
## Quick start [#quick-start]
The drop-in stack lives in the community repository:
```bash
git clone https://github.com/nowledge-co/community.git
cd community/docker
./nmemctl up
```
`nmemctl` is the lifecycle controller for this deploy. It starts the container, waits for `/livez`, prints your API key, and tells you the URL to open. If you already have a license code:
```bash
./nmemctl license activate
```
Other commands: `./nmemctl status` (health + key + URL), `./nmemctl logs -f`, `./nmemctl upgrade `, `./nmemctl wipe` (factory reset), `./nmemctl help` for the full list.
By hand, the same thing in three lines:
```bash
docker compose up -d
docker compose exec -T mem nmem key # print API key
docker compose exec -T mem nmem license activate # optional
```
Then open `http://:14242/app` and paste the API key when asked.
Hand this URL to Claude / Codex / Cursor / any agent, and it will know how to install, monitor, and upgrade your Mem server on its own. Destructive operations (wipe, key rotation, license activation) always stay with you.
```
https://raw.githubusercontent.com/nowledge-co/community/main/skills/nowledge-mem-docker/SKILL.md
```
That's the raw file: `curl` it and you get the markdown directly. The rest of this page is the human-readable version of the same workflow.
## What you get [#what-you-get]
* One container running the same Mem backend as the desktop app, with the web app available at `/app`.
* A non-root user, a read-only image filesystem, all data in three local directories next to your `compose.yaml`. No docker-volume idioms to learn: back them up with `rsync`, `restic`, `tar`, or ZFS snapshots.
* A small image (\~1.3 GB compressed) built straight from source. Same Python bundle as the desktop release.
* Multi-arch: one tag works on both `amd64` and `arm64` hosts.
## Where is my API key? [#where-is-my-api-key]
Mem generates an API key on first start. If you missed it, lost it, or want to rotate it, any of these works:
```bash
./nmemctl status # reprints key, license, URL, health
./nmemctl key # just the current key
./nmemctl key --rotate # rotate to a new value
./nmemctl logs | grep -A 1 "API Key" # peek at the first-run banner
```
The key lives in `./config/co.nowledge.mem.desktop/remote-access.json` on the host (mounted into the container at `/etc/nowledge-mem/...`), so it survives image upgrades. Backing up `./config` backs up the key. If you rotate, every existing client (the web UI, MCP clients, the `nmem` CLI on remote machines) needs the new value pasted back in.
### One-click installs (NAS app stores) [#one-click-installs-nas-app-stores]
All of the above needs a shell. If you installed from a NAS app store (Synology, QNAP, Unraid, and the like) with one click, you may not have one. For that case set **`NOWLEDGE_NAS_BOOTSTRAP: "1"`** in the compose `environment` block (it ships commented out, default off). Then open the web UI from a browser on the same network, go to **Settings → Access Anywhere**, and a "Finish setup: copy your access key" card lets you copy the key right there, no terminal needed.
It's deliberately narrow: opt-in only, it closes for good the first time the key is used, and the reveal is refused for anything arriving over the Access Anywhere tunnel. The server checks the visitor's address (including a reverse proxy's forwarded client header) and refuses public ones. On a standard Linux Docker host the real client IP is preserved, so this genuinely rejects outside visitors, but some networking setups present the bridge gateway instead, where a LAN client and an outside one look the same. Because you can't always be sure, only turn it on for a box on your trusted home network; if the port is exposed straight to the internet, retrieve the key with `nmemctl` instead.
## Where your data lives [#where-your-data-lives]
Three local directories sit next to `compose.yaml`. You own them, and standard tools work directly:
| Directory | Holds | Tier |
| ---------- | --------------------------------------------------------------------- | ------------------------------- |
| `./data` | Your graph, your conversations, your files | **Irreplaceable**, back this up |
| `./config` | Settings, license, plugin choices, your API key, your device identity | **Valuable**, back this up |
| `./cache` | Embedding models, search index projection | **Rebuildable**, safe to wipe |
Files are owned by UID 10001 inside the container; `./nmemctl up` chowns the directories for you on first run via a one-shot helper container, so you never type `chown` or `sudo` yourself.
When you upgrade with `./nmemctl upgrade ` (or `docker compose pull && docker compose up -d` by hand), all three directories stay in place. Your license stays activated, your data and conversations stay put, and the embedding model in cache means searches don't need to re-download anything. The only operation that resets you to a fresh install is `./nmemctl wipe`, which is the deliberate "wipe and start over" flow.
SELinux operators (RHEL / Fedora / Rocky): append `:Z` to each bind mount in `compose.yaml` so SELinux relabels the host directories for container access. The label is opt-in because it's destructive on first apply.
## Reach your server from anywhere [#reach-your-server-from-anywhere]
`cloudflared` is bundled inside the image, so Access Anywhere on Docker is turnkey. There is no sidecar to add and no `cloudflared service install` to run. The server starts and manages the tunnel for you.
Configure it from the web UI in **Settings → Access Anywhere**, or from the `nmem` CLI inside the container:
```bash
docker compose exec -T mem nmem config access ...
```
Once the tunnel is live, copy the URL and API key and connect any other device. The setup, key handling, and client connection steps are the same as the desktop app, so the full walkthrough lives on one page: [Remote Access](/docs/remote-access).
The terminal UI ships in the image too. Run it inside the container to configure Access Anywhere, reveal the API key, and check status without leaving the shell:
```bash
docker compose exec -it mem nmem tui
```
## Memory and growing data [#memory-and-growing-data]
The default `mem_limit: 4g` is sized for **passive** use of Mem: graph, web app, idle search. If you intend to use AI Now or Feed Agent actively on the server, raise it. As a rule of thumb:
| Your graph size | Recommended `mem_limit` |
| --------------- | -------------------------------------------------- |
| Under 200 MB | 2 GB |
| Under 1 GB | **4 GB** (compose default) |
| 1 to 4 GB | 8 GB |
| 4 to 16 GB | 16 GB |
| Over 16 GB | Tune explicitly (see `community/docker/README.md`) |
If a file upload or an agent query ever leaves the UI hanging on 500s, the safe recovery is `docker compose restart mem`. The image escalates its internal memory budget on the next start automatically, so the same workload should fit afterward. If it keeps happening, raise `mem_limit` per the table above.
On arm64 SBCs (Raspberry Pi 5, Orange Pi 5, etc.), the same table applies, but be aware these boards usually share host RAM with the GPU and other accelerators. Leave headroom for the OS.
## Check that search is fully working [#check-that-search-is-fully-working]
Search keeps working the whole time, so you never have to wait on it. `GET /health` tells you exactly which part is live:
```bash
curl -s http://:14242/health | python3 -m json.tool
```
Two fields matter:
* **`embedding.mode`** tells you how semantic search is running:
* `remote`: a remote embedding provider (for example Nowledge AI or your own key). Full semantic search.
* `local-gguf`: your bundled GGUF embedding model. Full semantic search.
* `local-hash-fallback`: no real embedder is configured, so semantic ranking is degraded. Keyword search still works. This is the signal to configure an embedding provider or model.
* **`reindex_needed`** is `true` when the search index is stale, usually because the embedding identity changed (you switched providers or models).
The server does not block boot to rebuild the index. It starts right away and serves keyword (FTS) search while the index catches up, so a stale index quietly falls back to keyword results rather than erroring. When you are ready, trigger the rebuild from **Settings → Memory Processing → Search**, or by hand:
```bash
curl -X POST -H "Authorization: Bearer $NMEM_API_KEY" http://:14242/search-index/reindex
```
If you would rather the server finish the rebuild before serving (the old behavior), set `NMEM_BOOT_AUTO_REINDEX=1` in the compose `environment` block. Most operators do not need this; the default fail-soft path keeps search available throughout.
## Verify the image came from us [#verify-the-image-came-from-us]
Each release is published with a Sigstore attestation. If you want to confirm the image you're about to pull came from our build pipeline (and not from somewhere that happens to have the same tag), run:
```bash
cosign verify docker.io/nowledgelabs/mem:0.9.4 \
--certificate-identity-regexp='https://github.com/nowledge-co/mem/.github/workflows/release-docker.yml@.*' \
--certificate-oidc-issuer='https://token.actions.githubusercontent.com'
```
A passing run shows the build's GitHub Actions identity. A failure means the image you pulled was not produced by our pipeline. Do not trust it.
The attestation is attached to the manifest, so the same `cosign verify` works for both `amd64` and `arm64`.
To confirm exactly which commit a running container was built from, read the build SHA:
```bash
docker compose exec -T mem nmem-server --build-info
```
The same value is in `GET /health` under `.build_sha`, which is handy when you want to verify a deployment over the network or from a script.
## TLS on a public host [#tls-on-a-public-host]
If the server is reachable from the internet and you want a real certificate, the same `community/docker/` directory ships a Caddy sidecar:
```bash
export NOWLEDGE_DOMAIN=mem.example.com
export NOWLEDGE_LE_EMAIL=you@example.com
docker compose -f compose.yaml -f compose.tls.yaml up -d
```
You need a DNS record pointing at the host, ports 80 and 443 open for the Let's Encrypt challenge, and **Docker Compose v2.24.4 or newer** (the overlay uses a YAML merge tag that earlier versions silently ignore). Caddy renews the certificate automatically.
## Backups and migration [#backups-and-migration]
Two layers, pick the one that matches your move:
**Volume-level snapshot** (same image version on both ends, fastest restore):
```bash
./nmemctl export # stop, tar ./data ./config ./cache, restart
./nmemctl export --no-cache # smaller archive, skip rebuildable cache
./nmemctl import mem-export--.tar.gz # restore on the new host
```
**Application-level dump** (cross-version, or migrating from a `.deb` / desktop install, uses the same portable JSONL format the desktop app uses for "Export to file"):
```bash
./nmemctl backup-app # produces mem-app-export--.zip
./nmemctl restore-app mem-app-export--.zip
```
For the app-side guide to this portable export format, read [Back Up, Export, and Import](/docs/data-portability).
Both flows leave the `machine_id` behind on purpose: the destination gets a fresh device identity and re-activates the license on first launch (consumes one seat). Retire the source server after a successful migration, since running both side-by-side diverges state.
You can also use `rsync`, `restic`, `borg`, ZFS snapshots, or plain `tar` directly against `./data` and `./config`; they're just host directories. Stop the container first (`./nmemctl down`) for a guaranteed-consistent snapshot, then `./nmemctl up` afterward.
Application-level dump is also how you migrate between architectures (e.g. moving from an amd64 VPS to an arm64 NAS). Volume-level snapshots are tied to the source architecture's data layout for some on-disk projections, so cross-arch moves should go through `backup-app` / `restore-app`.
## Upgrade from the web UI (optional) [#upgrade-from-the-web-ui-optional]
By default, upgrading a self-hosted Mem server means SSH-ing in once per release and running `./nmemctl upgrade `. If you'd rather upgrade from the same web app you use Mem in, turn auto-update on once:
```bash
./nmemctl auto-update enable
```
This path is only for the official `community/docker` deployment. NAS app-store installs, NAS Container Manager templates, Portainer stacks, Unraid templates, and custom compose files should be updated through the system that created them. Mem can still show that a newer version exists, but it should not rewrite an unknown deployment layout.
That generates a per-deploy token, adds a small companion container that handles the upgrade work, and allows Install to be triggered from the browser. After this:
* **Title-bar badge** lights up when a newer Mem image is published, the same way the desktop app signals updates.
* **Settings → Server card** shows the current version, the latest published version, a Download button (background pull, no downtime), and an Install button (about 30 seconds of downtime, with a snapshot taken before the container is recreated).
* **Skipping versions works.** If you're on 0.9.2 and 0.9.4 is the latest, Install moves you directly to 0.9.4. Forward-only schema migrations run in order on the new image's first boot.
Before turning it on:
* The companion container mounts `/var/run/docker.sock`, which is why this stays opt-in. That container is root-equivalent on the host. The Mem container itself never gets socket access.
* **Remote Install is a deliberate opt-in.** Checking for updates always works from the web UI, but Download and Install are loopback-only until `NOWLEDGE_ADMIN_REMOTE_OPS=1` is set. `auto-update enable` sets that flag for you, because clicking Install from a browser is a server-side state change. Only enable this on a trusted network.
* Every Install takes a snapshot of `./data` and `./config` into `./cache/_pre-upgrade-.tar.gz` before recreating the container. The last three snapshots stay on disk. If the new image fails to come up, the web UI shows the snapshot path so you can SSH in and run `./nmemctl import --force` to restore the previous state.
```bash
./nmemctl auto-update status # current state, last pull, retained snapshots
./nmemctl auto-update rotate # rotate the updater token
./nmemctl auto-update upgrade # bump the companion container's image
./nmemctl auto-update disable # remove the companion container; keep the snapshots
```
## Full operator notes [#full-operator-notes]
For the complete operator contract (every environment variable, security hardening details, the device-identity invariant, troubleshooting recipes), see [`community/docker/README.md`](https://github.com/nowledge-co/community/tree/main/docker) in the community repository.
## Related [#related]
* [Installation](/docs/installation): The desktop app path, which is what most users want.
* [Linux Server Deployment](/docs/server-deployment): `.deb` install with a systemd unit, for Linux servers where you'd prefer apt-managed updates over containers.
* [Back Up, Export, and Import](/docs/data-portability): Application-level export format and restore flow.
* [Remote Access](/docs/remote-access): Access Anywhere keys, API access, multi-device sync. Applies identically to the Docker deployment.
* [LLM Providers](/docs/llm-providers): Required for background intelligence (daily briefings, insights, graph enrichment).
* [Troubleshooting](/docs/troubleshooting): Common operator issues, including the headless container path.
# Use Nowledge Mem with fully local models (/docs/fully-local-models)
Nowledge Mem can keep both your knowledge and the model calls that process it on your own machine. A local inference server such as LM Studio or Ollama exposes a loopback endpoint; Mem sends requests to that endpoint instead of a cloud model provider.
This guide gives you a practical first setup, a way to verify it, and the boundaries you need to check before calling the whole workflow fully local.
The content processing you enable, including memory organization, agent responses, embeddings, and optional vision or OCR, must call only built-in models or endpoints on the same machine. No content is sent to a cloud model, and a local failure must not silently fall back to one.
Changing only the model used for memory processing does not, by itself, prove that every enabled workflow is local.
## Local AI beyond the Mac since version 0.10 [#local-ai-beyond-the-mac-since-version-010]
Since version 0.10, Nowledge Mem's zero-Python local runtime has covered desktop and headless Linux deployments. Official Docker images include a CPU build plus opt-in CUDA and Vulkan builds. You can run Mem on personal hardware or on your own Linux server.
The bundled Gemma 4 model is multimodal. Vision is the part integrated today: Library uses it for scanned PDFs, text in images, and other documents that need visual understanding. The underlying model also provides a foundation for audio, but production audio routing, PII filtering, and audio-meeting processing remain future directions rather than features delivered by this page today.
Beyond the model bundled with the app, Nowledge Mem gives [Lemonade](https://lemonade-server.ai/), Ollama, and LM Studio first-class local-provider support. Special thanks to community contributor and power user [abn](https://github.com/abn), who did substantial work on the Lemonade integration.
## Before you start [#before-you-start]
You need:
* Nowledge Mem running in local desktop or local-server mode
* A local inference server, such as [Lemonade](https://lemonade-server.ai/), [LM Studio](https://lmstudio.ai/), or [Ollama](https://ollama.com/)
* A chat model loaded by that server
* Enough memory for the model and the rest of your daily applications
Lemonade's default OpenAI-compatible endpoint is `http://127.0.0.1:13305/v1`, LM Studio's is `http://127.0.0.1:1234/v1`, and Ollama's is `http://127.0.0.1:11434/v1`. If Mem and the model server run in different containers or on different machines, use an address that Mem can reach; inside a container, `127.0.0.1` refers to that container itself.
## Start the local model server [#1-start-the-local-model-server]
Load a model in Lemonade, LM Studio, or Ollama, start the local server, and confirm that its OpenAI-compatible `/v1` endpoint is running.
Verify that the server reports at least one model:
```bash
# Lemonade
curl http://127.0.0.1:13305/v1/models
# LM Studio
curl http://127.0.0.1:1234/v1/models
# Ollama
curl http://127.0.0.1:11434/v1/models
```
The model ID returned here is the value you should use in Mem. Do not guess it from the model's display name.
## Add the provider in Mem [#2-add-the-provider-in-mem]
1. Open **Settings → Providers**.
2. Add **Lemonade**, **LM Studio**, or **Ollama**.
3. Enter the loopback URL and the exact model ID reported by the server.
4. Leave the API key empty unless your local server requires one.
5. Test the connection, then save the provider.
If you use another local runtime, add an **OpenAI-compatible custom endpoint**. It must implement Chat Completions or the Responses API format you select.
## Route every enabled model purpose [#3-route-every-enabled-model-purpose]
Provider setup and workload routing are separate. In the Providers screen, check each purpose:
| Purpose | Fully local choice | What it affects |
| ---------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Default** | Your local provider | The model inherited by any purpose set to "Same as default" |
| **Agents** | Your local provider, or "Same as default" when Default is local | Background Intelligence, AI Now, Timeline, the browser-extension agent, and other agent workflows |
| **Embedding** | **Built-in local** | Search indexing and vector retrieval |
| **Vision / OCR** | Built-in local vision or a local vision-capable provider; otherwise leave those workflows unused | Image understanding and OCR requests used by Library |
Keeping **Embedding** on **Built-in local** is the simplest local setup. If you switch to a different embedding model or dimension, follow the reindex prompt before judging search results.
If an external local model cannot process images, do not assign it to Vision
or OCR and assume those features are covered. Use the built-in local vision
model, another local vision-capable model, or keep image workflows disabled.
Check the route again whenever you enable a new enrichment feature.
## Verify the setup [#4-verify-the-setup]
Use a small, observable test:
1. Disconnect or disable every cloud provider in **Settings → Providers**.
2. Keep the local inference server's request log visible.
3. Create a test memory with one durable preference and one piece of temporary noise.
4. Run the relevant Background Intelligence action, then ask AI Now to retrieve the durable preference.
5. Confirm that requests appear only in the local server log and that the result is saved or returned as expected.
6. Stop the local server and repeat once. The action should fail visibly; it should not succeed through a cloud fallback.
Success means the local server handled the request, Mem produced the expected output, and no remote provider was used.
## Model sizing: one user's Apple Silicon benchmark [#model-sizing-one-users-apple-silicon-benchmark]
Community member [Versun](https://x.com/VersunPan) tested three 4-bit models on a Mac mini with an M4 Pro and 64 GB of unified memory. All three passed the same controlled memory-organization task three times. The differences were mainly latency and memory use, not a broad measure of intelligence.
| Model | Cold load | Resident memory task | Long-input TTFT | LM Studio total peak RSS |
| ------------------- | --------: | -------------------: | --------------: | -----------------------: |
| Gemma 4 12B GGUF | 3.82 s | 7.38 s | 36.79 s | 10.65 GiB |
| Gemma 4 26B-A4B MLX | 8.17 s | 2.68 s | 13.83 s | 17.69 GiB |
| Qwen3.6 35B-A3B MLX | 11.55 s | 2.64 s | 9.87 s | 17.72 GiB |
His practical choices were:
* **Under 32 GB:** the 12B GGUF model leaves more room for other applications.
* **Between 32 and 64 GB:** the 26B-A4B MLX model is a safer balance.
* **64 GB and a resident model:** the 35B-A3B MLX model gave the best overall latency in this test.
* **Frequent load and unload:** the 26B-A4B model had the lower combined load-plus-task time.
These results come from one machine, one runtime version, and one fixed prompt. Shared memory pages can also make summed RSS larger than the exact reduction in free system memory. Treat the table as a sizing reference, then test your own workload.
Read [Versun's original Chinese benchmark](https://x.com/VersunPan/status/2077967423689707679) or the [formatted republication on the Nowledge Labs blog](https://nowledge-labs.ai/zh/blog/nowledge-mem-local-model-benchmark).
## Privacy boundaries to review [#privacy-boundaries-to-review]
A local model endpoint keeps inference local, but other product features can still use the network:
* Sync and remote access send the data required for those features to the service you configured.
* Browser connectors and imports fetch content from their source services.
* Updates, sign-in, and external links may contact their respective services.
* A custom endpoint on another device is self-hosted, but it is no longer on the same machine.
If your requirement is an offline machine rather than simply local inference, disable sync and remote providers, disconnect the network, and rerun the verification above.
## Troubleshooting [#troubleshooting]
### Mem cannot list models [#mem-cannot-list-models]
Confirm that the model server is running and that the URL ends in `/v1`. Use `curl` against `/v1/models` before debugging Mem.
### The connection works, but agent tasks fail [#the-connection-works-but-agent-tasks-fail]
The model may not support the chat or tool-calling behavior used by that workflow. Try a stronger instruction model and verify that **Agents** points to it.
### The first request is much slower [#the-first-request-is-much-slower]
That is usually a cold load. Keep the model resident if your runtime and available memory allow it. Measure cold-load time separately from steady-state requests.
### Search changed after switching embeddings [#search-changed-after-switching-embeddings]
Embedding vectors from different models or dimensions are not interchangeable. Complete the requested reindex and test search again.
Next, see [LLM Providers](/docs/llm-providers) for provider-specific settings and context-window guidance.
# Getting Started (/docs/getting-started)
Save one real memory in the Timeline and confirm you can find it again. If you have not picked a path yet, read [Start Here](/docs/start-here) first.
## The Timeline [#the-timeline]
Open Nowledge Mem. You see one input and a timeline below it.
### Save a thought [#save-a-thought]
Type a decision, an insight, anything worth keeping. Hit enter.
Nowledge Mem handles the rest: title, key concepts, graph connections. You just write. Open the Graph view later and you'll see it already linked to related memories.
### Ask a question [#ask-a-question]
Type a question: *"What did I decide about authentication last month?"*
The answer comes from **your own knowledge**: not the internet. Every question searches your full memory and synthesizes an answer from what you've written and saved.
### Drop a URL or file [#drop-a-url-or-file]
Paste a URL. The page gets fetched, parsed, and stored as a searchable source. Drop a PDF, a Word doc, a presentation. Same treatment. Each input grows your knowledge base.
## Your First Win [#your-first-win]
Before you connect any AI tool, prove the loop in the app itself:
1. Save one memory
2. Ask for it back
3. Confirm the answer reflects your own knowledge
If you want a concrete verification checklist, use [How To Know Mem Is Working](/docs/verify-it-works).
## Bring in conversations you already have [#bring-in-conversations-you-already-have]
If you are not starting from an empty slate (**coding assistant logs on disk**, **ChatGPT / DeepSeek / ChatWise / Alma exports**, or **one saved `.md` thread**), use **[Import existing conversations](/docs/import-existing-conversations)**. There you get Threads → Import spelled out: disk scans, **bulk** vendor files, **single** files, and the extension on the **tab you have open** (not your full web chat history in one shot).
## Connect Your First Tool [#connect-your-first-tool]
Do not start by picking a tool from a long list. Give your AI tool one prompt and let it choose the best supported setup path:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for the AI tool I am using.
```
Paste this into Claude Code, Grok Build, Codex, Cursor, Gemini CLI, Copilot CLI, OpenClaw, Hermes, Droid, Alma, Bub, Pi, OpenCode, or Claude Desktop. The agent fetches the install contract, detects which host it is in, uses the matching setup path, verifies the connection with `nmem status`, and asks you to restart the host when needed. Command-line hosts can usually be installed directly. App-based hosts may still require a user-confirmed marketplace step.
Pick the AI tool you actually use most. Run the prompt there. Restart that tool. Stop. Adding more tools later is the same one-prompt gesture each time.
### Remote or cross-device setup [#remote-or-cross-device-setup]
If Mem runs on the same machine as the AI tool, the generic prompt above is enough.
If the AI tool runs on another machine, or if you are using a managed or self-hosted remote Mem server, configure the shared client settings first:
```bash
nmem config client set --url https://your-mem-server.example --api-key nmem_...
```
In the desktop app, remote URL and key controls live under **Settings → Access Anywhere**.
### When the prompt does not fit [#when-the-prompt-does-not-fit]
A small set of surfaces install differently:
* **Web chat (ChatGPT, Claude.ai, Gemini, NotebookLM, Poe)**: install the [Browser Extension](/docs/integrations/browser-extension) from the Chrome Web Store and open the side panel.
* **Raycast**: install from the Raycast Store. See [Raycast](/docs/integrations/raycast).
* **Trajectory extractors (Windsurf, Antigravity)**: external CLIs that export sessions for one-time import. See [Import existing conversations](/docs/import-existing-conversations).
For per-tool behavior reference once the connect is done (skills, recall strategy, distillation), see the individual connector pages. The connect itself is one prompt.
## Other Ways Content Reaches Mem [#other-ways-content-reaches-mem]
* **Existing chats (map first)**: [Import existing conversations](/docs/import-existing-conversations): coding agents on disk, vendor exports, single files, and the extension on the tab you are using
* **Web chat (current tab)**: the [browser extension](/docs/integrations/browser-extension) saves the session you work with in the panel, not a full account export (use bulk import for that)
* **Thread formats (reference)**: [Threads](/docs/threads) for Markdown rules and bulk file specifics
* **Manual**: create memories in the Memories view with **+ Create**, or from any terminal with `nmem m add` ([CLI reference](/docs/cli))
## What to Try [#what-to-try]
Once you have a few memories saved, try these in the Timeline:
**"Which of my ideas have evolved the most?"** Finds ideas that went through multiple revisions and tells the story chronologically.
**"Summarize my recent coding conversations"** If your coding conversations are already flowing into Mem through auto-sync, native save paths, or imports, this lists and summarizes your latest sessions.
**"Search my documents for \[topic]"** Full-text search across everything in your Library: PDFs, spreadsheets, code files, anything you dropped in.
These get more powerful as your knowledge grows. After a month, the results will surprise you.
## Next Steps [#next-steps]
* **[Start Here](/docs/start-here)**: Pick the first path that matches your real workflow
* **[Using Nowledge Mem](/docs/usage)**: Daily workflow, search, and how your knowledge grows
* **[How To Know Mem Is Working](/docs/verify-it-works)**: Verify the app loop and connected tools
* **[Memories](/docs/memories)**: Atomic knowledge you can search, connect, and evolve
* **[Import existing conversations](/docs/import-existing-conversations)**: Map every import path in one page
* **[Threads](/docs/threads)**: Formats, import UI, and distillation
* **[AI Now](/docs/ai-now)**: Personal AI with full access to your knowledge base
* **[Connectors](/docs/integrations)**: Connector reference for each AI tool
# Import existing conversations (/docs/import-existing-conversations)
Mem can bring in prior chats in three ways: **coding agents we discover on disk**, **files you export from an app**, and **the browser extension on the tab you are looking at**. This page matches those options to the buttons in **Threads → Import** (and **Connectors → Thread Import**).
Bulk filenames, Markdown headers, and odd edge cases live in **[Threads](/docs/threads)**.
## Pick what matches you [#pick-what-matches-you]
| You have… | In Mem | Notes |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Claude Code, Cursor, Codex, or OpenCode** logs on disk | **Threads** → **Import** → **Find AI Conversations** (same entry under **Connectors → Thread Import**) | Pick sessions after Mem scans |
| Older local sessions from **Antigravity, Claude Code, Grok Build, Codex, Craft Agent, Gemini CLI, Kimi Code, Kimi Work, MiMo Code, OpenCode, OMP, or Pi**, especially when Mem runs on another machine | Run `nmem t sync --from ...` on the machine where that agent stores its sessions | Preview first; add `--apply` when the list looks right |
| A **full export** from ChatGPT, **Google Gemini / AI Mode**, **Claude** (claude.ai / Claude Desktop), DeepSeek, ChatWise, Alma, or **Raycast AI** (via exporter JSON) | **Threads** → **Import** → **Bulk Import** | One file (see table below) |
| **One** `.md` thread or similar | **Threads** → **Import** → **Single Thread** | See [Single thread](/docs/threads#single-thread) |
| A chat **open in the browser right now** | [Browser extension](/docs/integrations/browser-extension) | Sends the **focused** session from the tab you use with the extension, not your full account history |
## Coding agents (disk) [#1-coding-agents-disk]
**Find AI Conversations** looks for local session data from Claude Code, Cursor, Codex, and OpenCode. Nothing is saved until you choose what to import.
Plugins can also keep threads in sync over time; this scan is mainly for **catching up** (new machine, or first setup).
For connector history that is not listed in the desktop scanner, use the CLI backfill path. Supported sources today are `antigravity`, `claude-code`, `grok`, `codex`, `craft-agent`, `gemini-cli`, `kimi-code`, `kimi-work`, `mimo-code`, `opencode`, `omp`, and `pi`.
```bash
# Project-scoped coding agents
nmem t sync --from codex --all-projects --limit 20
nmem t sync --from craft-agent --all-projects --limit 20
nmem t sync --from grok --all-projects --limit 20
# Pi sessions
nmem t sync --from pi --limit 20
# Other local coding-agent stores
nmem t sync --from antigravity --limit 20
nmem t sync --from kimi-code --limit 20
nmem t sync --from kimi-work --limit 20
nmem t sync --from mimo-code --limit 20
nmem t sync --from omp --limit 20
```
The first run is a preview. Replace `codex` with another supported source when needed. When the list looks right, run the same command with `--apply`.
Current Antigravity CLI and Antigravity 2.0 sessions keep a documented local `transcript.jsonl`, which `nmem t sync --from antigravity` reads directly. The command imports only user and assistant turns and keeps the original conversation ID, so it converges with live capture instead of creating a second thread.
Some older sessions exist only in Antigravity's private cache. For those, use the [Antigravity Trajectory Extractor](https://github.com/jijiamoer/antigravity-trajectory-extractor) while Antigravity is running, export JSON, then preview it with `nmem t sync --from antigravity --session-dir `. Mem does not guess at private protobuf or database formats.
Run `nmem t sync` on the laptop or server where the AI tool keeps its session files. The command uses your normal `nmem` client config, so it can upload to local Mem or a remote Mem server. The remote server does not need direct access to your `~/.codex`, `~/.craft-agent`, `~/.grok`, `~/.claude`, `~/.gemini`, `~/.kimi-code`, Kimi Work runtime, `~/.pi`, `~/.omp`, OpenCode, or MiMo Code data.
## Export files (bulk) [#2-export-files-bulk]
**Bulk Import** expects the real export each vendor hands you:
| App | File | Export |
| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ChatGPT** | `chat.html` (inside their ZIP) | Settings → Data controls → Export data |
| **Google Gemini Apps / AI Mode** | The Takeout ZIP, or `MyActivity.html` after you extract it | [takeout.google.com](https://takeout.google.com) → **Deselect all** → **My Activity** → **All activity data included** → select **Gemini Apps** or **AI Mode** → export. Do **not** select the top-level **Gemini** checkbox; that is for Gems settings, not chat history. |
| **Claude** | `data-…-batch-….zip` (contains `conversations.json` + `memories.json`) | Web or Desktop: initials → **Settings** → **Privacy** → **Export data**, then Anthropic emails a download link (see [their guide](https://support.claude.com/en/articles/9450526-how-can-i-export-my-claude-data)). Not available from Claude mobile apps. |
| **DeepSeek** | `deepseek_conversations.json` | chat.deepseek.com → Settings → Data → Export data |
| **ChatWise** | `.zip` of chats | Export all chats from ChatWise |
| **Alma** | `alma-backup-…zip` with `threads.json` | Settings → Data → Export all threads |
| **Raycast AI** | `raycast_ai_chats.json` (or any `.json` from the tool) | No built-in export, so use **[raycast-ai-exporter](https://github.com/daveonkels/raycast-ai-exporter)** (macOS; see its README) |
Drop the file in as downloaded; Mem figures out the format.
For Gemini and AI Mode, Google stores the chat text in **My Activity**, not in the top-level Gemini export. You can upload the full Takeout ZIP, or extract it and upload `Takeout/My Activity/Gemini Apps/MyActivity.html` or `Takeout/My Activity/AI Mode/MyActivity.html` directly.
Imported conversations are searchable right away as Threads. Mem does not automatically turn every imported conversation into Memories, because a large archive can spend a lot of AI tokens and produce noisy results. Start by searching the imported threads; distill only the decisions, facts, procedures, or lessons you want to keep as long-term memory.
When you do want to process a backlog, go to **Threads**, click **Select**, choose the current page or **Select all results**, then click **Plan distillation**. Mem plans a small safe wave instead of queuing hundreds of conversations at once; very large threads are deferred for a separate pass.
Use the **ZIP** from the email (for example `data-2026-04-01-08-10-35-batch-0000.zip`). Mem imports **all chats** from `conversations.json` and saves Claude's **profile memory** from `memories.json` as a labeled memory card after the threads you selected finish importing. If you only extract `conversations.json`, you get threads only.
The exporter is a third-party script: you keep Raycast’s **AI Chat** window open, grant **Accessibility** to your terminal, and it writes structured JSON (sessions with `role` / `content` messages). Dates in the file are **approximate** (sidebar groupings). Same JSON works in **Bulk Import** and `nmem t import --file`.
## Browser: focused tab only [#3-browser-focused-tab-only]
The extension does **not** download your entire web chat history. It works with the **session in the active tab** when you capture, useful for what you are doing **now**. For **everything the provider ships in one archive**, use **Bulk Import** (or your coding-agent scan where that applies).
## One file [#4-one-file]
**Single Thread** is for conversation Markdown, Cursor exports, and other single-file flows; details in **[Threads](/docs/threads#single-thread)**.
## Where to click [#where-to-click]
* **Threads** → **Import**: Find AI, Bulk, Single.
* **Connectors** → **Thread Import**: same story, plus shortcuts into **Threads**.
## Next [#next]
* **[Threads](/docs/threads)**: formats and distillation
* **[Getting Started](/docs/getting-started)**: first day in the app
* **[Connectors](/docs/integrations)**: AI tools, MCP, extension
# Nowledge Mem (/docs)
Your AI tools do not remember your work for you. Nowledge Mem does.
0.10.0 rebuilds the core engine in native Rust: faster and lighter on every platform, now running natively on Windows and Linux, reading images on-device, and able to use your GPU. The download is roughly a quarter the size and uses about a third less memory. See the [changelog](/changelog) for what is live and what is rolling out.
It is your memory layer for AI work. Save a decision, an insight, a useful source, or a conversation. Mem makes it searchable, connects it to what you already know, and lets the tools you connect start from the same context.
You do not need to wire everything at once. Save one thing, find it again, then let one real tool use it. Once that loop works, Mem becomes much easier to understand.
If you want to use Mem across multiple devices, that is now supported too: run one Mem on an always-on machine, then connect your desktop, web, mobile, and supported tools to that same knowledge base. See [Sync Across Devices](/docs/sync).
If you're new here, the shortest path is:
1. [Install the app](/docs/installation)
2. [Save your first memory](/docs/getting-started)
3. Connect any AI tool with one copy-paste, see [Start Here](/docs/start-here)
4. [Confirm Mem is actually working](/docs/verify-it-works)
The connect step starts with one prompt: *"Read [https://mem.nowledge.co/SKILL.md](https://mem.nowledge.co/SKILL.md) and follow the instructions to install or update Nowledge Mem for the AI tool I am using."* Paste it into Claude Code, Grok Build, Codex, Cursor, Gemini CLI, Copilot CLI, OpenClaw, or another supported host. Command-line hosts can usually install directly; app-based hosts may ask you to confirm a marketplace step.
## Connect Any AI Tool [#connect-any-ai-tool]
Paste this into your AI tool. The agent reads it, detects the host, uses the right setup path, verifies Mem, and tells you what changed:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for the AI tool I am using.
```
This works in Claude Code, Grok Build, Codex, Cursor, Gemini CLI, Copilot CLI, OpenClaw, Hermes, Droid, Alma, Bub, Pi, OpenCode, and Claude Desktop. For remote or cross-device access, configure the shared client settings with `nmem config client set --url ... --api-key ...`; in the desktop app, remote URL and key controls live under **Settings → Access Anywhere**.
For per-tool behavior reference (skills, recall strategy, distillation), the individual connector pages still apply once the connect is done:
Native connector with automatic briefing, recall, and session capture
Native connector for the coding agent, with startup context, hooks, and session capture
Native connector with Working Memory, routed recall, and clear handoff behavior
Native extension with commands, hooks, and real session save
Native connector with bundled MCP, AGENTS guidance, and automatic Codex thread capture
Native connector with startup context, recall guidance, and session capture
Full plugin guide for lifecycle capture, recall, and distillation
One-click extension for search, save, and memory updates
Capture conversations from supported web AI chat platforms
## Import Your Documents [#import-your-documents]
Drop a PDF, Word doc, or presentation into the Library. It gets parsed and indexed alongside your memories. When you ask a question in the Timeline, the answer draws from both.
## Local-First Privacy [#local-first-privacy]
Nowledge Mem is local-first. Your knowledge lives on your device by default. You can connect a remote LLM when you want stronger processing, but your data never touches Nowledge servers.
For backup or one-time migration, use [Back Up, Export, and Import](/docs/data-portability). Mem exports a portable, text-based bundle so your knowledge stays under your control.
The first page to read after installation
Get started in minutes
Your first five minutes
Fast checks for search, capture, and connected tools
# Installation (/docs/installation)
Nowledge Mem can be downloaded directly:
* **Download**: open the [download page](/download) for macOS, Windows, and Linux builds
* **Manage access**: sign in at [mem.nowledge.co/licenses](https://mem.nowledge.co/licenses) for Lifetime License devices and receipts
Do not configure everything at once. After the app opens, go to [Start Here](/docs/start-here), save one memory in the Timeline, and choose only one connection path for the tool you actually use.
## System Requirements [#system-requirements]
Minimum system requirements:
| Requirement | Specification |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Operating System** | macOS 15 or later Windows 10 or later Linux x86\_64 (Ubuntu 22.04+, Debian 12+, or AppImage for other distros) |
| **Memory (RAM)** | 16 GiB minimum |
| **Disk Space** | 10 GiB available |
| **Network** | If using a proxy, ensure it bypasses `127.0.0.1` and `localhost` |
**Linux headless servers** are also supported. See the **[Linux Server Deployment](/docs/server-deployment)** guide to run Nowledge Mem on servers without a desktop environment.
**GPU acceleration.** On a Mac with Apple Silicon, on-device work (local search and the built-in model) uses the GPU automatically through Metal, with nothing to set up. On Windows and Linux the desktop app runs on the CPU, which is the right choice for almost everyone. If you want GPU acceleration on a server or workstation, run Nowledge Mem with Docker: the CUDA image (NVIDIA) and the Vulkan image (AMD and Intel) are described in **[Docker Deployment](/docs/docker)**.
## Installation Steps [#installation-steps]
## Step 1: Install the Application [#step-1-place-app]
Drag Nowledge Mem to your `/Applications` folder.
Nowledge Mem requires the **Microsoft Visual C++ Redistributable** to run on Windows. If you haven't installed it yet, download and run the installer first:
Download the Windows installer from [mem.nowledge.co/licenses](https://mem.nowledge.co/licenses) and run it. Future updates install automatically from within the app, so there is no need to download again.
The Microsoft Store version has been discontinued. If you previously installed Nowledge Mem from the Store, uninstall it first via **Settings → Apps → Nowledge Mem → Uninstall**, then install the version linked above. Your data is preserved; only the app binary is replaced.
Install via the APT repository for automatic updates, or download the `.deb` / `.AppImage` directly.
For terminal downloads, use the commands below as written.
They include a browser User-Agent because some download endpoints return `403` to plain `curl` / `wget` requests.
If this machine is a headless Linux server, use the APT or `.deb` path and then follow [Linux Server Deployment](/docs/server-deployment).
AppImage is a portable fallback, not the main server setup path.
One-line setup that adds the GPG key and repository, then installs:
```bash
curl -fsSL https://nowledge-co.github.io/community/apt/install.sh | sudo bash
sudo apt-get install nowledge-mem
```
Future updates arrive automatically via `sudo apt-get upgrade`.
```bash
BROWSER_UA='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
# Download the latest .deb
curl -A "$BROWSER_UA" -L -o nowledge-mem.deb https://nowled.ge/download-mem-deb
# Install
sudo dpkg -i nowledge-mem.deb
sudo apt-get install -f # fix any missing dependencies
```
```bash
BROWSER_UA='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
# Download the latest AppImage
curl -A "$BROWSER_UA" -L -o nowledge-mem.AppImage https://nowled.ge/download-mem-appimage
# Make it executable and run
chmod +x nowledge-mem.AppImage
./nowledge-mem.AppImage
```
This does not install the `nmem` CLI into your PATH. For server use, prefer APT or `.deb`.
## Step 2: Launch the Application [#step-2-first-boot]
Double-click the Nowledge Mem icon in your Applications folder to launch the app for the first time.
If the app takes too long to start or shows errors:
* **Service timeout**: If you see "It took too long to start the service", this usually means a global proxy is preventing access to `localhost`. Disable your proxy and try again.
* **macOS version**: Ensure you're running macOS 15 or later. Older versions are not supported.
* **Need more help?** Check the [Troubleshooting Guide](/docs/troubleshooting) to view logs and get detailed diagnostics. You can share logs with our community or email support for assistance.
After installation, launch Nowledge Mem from the Start menu. Search for "Nowledge Mem".
If the app takes too long to start or shows errors:
* **Missing Visual C++ Runtime**: If you see `DLL load failed` or the app exits on startup, install the [Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe) and restart the app. See [Troubleshooting](/docs/troubleshooting#windows-missing-visual-c-runtime) for details.
* **Service timeout**: If you see "It took too long to start the service", this usually means a global proxy is preventing access to `localhost`. Disable your proxy and try again.
* **Need more help?** Check the [Troubleshooting Guide](/docs/troubleshooting) to view logs and get detailed diagnostics. You can share logs with our community or email support for assistance.
Launch Nowledge Mem from your application menu, or run it from the terminal:
```bash
nowledge-mem
```
If the app takes too long to start or shows errors:
* **Service timeout**: If you see "It took too long to start the service", this usually means a global proxy is preventing access to `localhost`. Disable your proxy and try again.
* **Missing libraries**: If you see `libwebkit2gtk` errors, install the dependencies: `sudo apt-get install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1`
* **Need more help?** Check the [Troubleshooting Guide](/docs/troubleshooting) to view logs and get detailed diagnostics.
## Step 3: Install The Required Models [#step-3-download-models]
After launching Nowledge Mem, install the models the app asks for (approximately 2.4GB total):
* **Apple Chip Mac**: On-device LLM is supported.
* **Windows**: Remote LLM is required.
* **Intel Mac**: Remote LLM is required.
* **Linux**: Remote LLM is required.
### Check notifications [#check-notifications-step]
You'll see download prompts in the top-right corner of the app
### Navigate to models [#navigate-to-models-step]
Click the notification button, or go to **Settings** → **Models**
### Install models [#install-models-step]
Click **Install** on the model card the app prompts you to download
The download will begin automatically, and you can monitor the progress:
Depending on your internet connection, the download may take 5-15 minutes. The models only need to be downloaded once.
## Optional: Install The Browser Extension [#step-4-browser-extension]
The **Nowledge Mem Exchange** browser extension is optional. Install it if you want to capture insights and thread backups from supported web AI chat platforms.
After installing, click the extension icon to open the side panel or sidebar. Configure your LLM provider in **Settings** to enable auto-capture.
ChatGPT, Claude, Gemini, NotebookLM, Microsoft Copilot, Perplexity, DeepSeek, Kimi, Qwen, POE, Manus, Grok, and more. The extension can capture valuable insights and full thread backups from supported sites. See the [Browser Extension guide](/docs/integrations/browser-extension) for details.
## After Installation [#after-installation]
Installing the app gives you the memory system itself. The next step is not "configure everything." It is to prove one real workflow:
1. Save one memory in the Timeline
2. Choose one path that matches the tool you already use
3. Confirm it works before adding anything else
For most people, the three main paths are:
* Use a **dedicated connector** when your tool has one: Claude Code, Grok Build, Codex, Gemini CLI, OpenClaw, Hermes Agent, Alma, Cursor, Droid, OpenCode, Copilot CLI, Pi, or Bub
* Use the **browser extension** if your work mostly happens in ChatGPT, Claude, Gemini, Microsoft Copilot, or other supported web chats
* Use the app itself first if you want to learn Mem before wiring external tools
Everything else, reusable packages, `nmem` CLI, and direct MCP, is secondary unless your tool actually needs it.
If you already know you want one always-on Mem and several connected devices, read [Sync Across Devices](/docs/sync) first, then follow [Access Anywhere](/docs/remote-access) for setup.
## Mobile Apps (Preview) [#mobile-apps-preview]
Native iOS and Android apps are available as preview clients. They connect to your desktop Mem through [Access Anywhere](/docs/remote-access): your data stays on your main machine, and the mobile app gives you search and capture on the go.
* **iOS**: [Join the TestFlight](https://nowled.ge/mem-ios)
* **Android**: [Download the APK](https://nowled.ge/mem-android)
Both require a running desktop Mem with Access Anywhere enabled.
## Next Steps [#next-steps]
* **[Start Here](/docs/start-here)**: The shortest path for new users
* **[Getting Started](/docs/getting-started)**: Your first five minutes with the Timeline
* **[How To Know Mem Is Working](/docs/verify-it-works)**: Verify search, capture, and tool connections
* **[Connectors](/docs/integrations)**: Connect Claude Code, Grok Build, Codex, Cursor, and other AI tools
* **[Sync Across Devices](/docs/sync)**: Understand the single-Mem, multi-client sync model
* **[Linux Server Deployment](/docs/server-deployment)**: Run headless on a Linux server
# Knowledge Graph (/docs/knowledge-graph)
Everything you save in Mem lives on one [Super Knowledge Graph](https://nowledge-labs.ai/blog/building-memory-systems-for-ai-agents#heading-11): three knowledge forms (Trace, Unit, Crystal) on top of seven node types and eleven edge types, designed for *progressive disclosure*. Light queries first. Walk relationships when you need more context. Walk the version chain when you need history. Look at communities and Crystals when you want the big picture.
The Knowledge Graph view is where that graph stops being a metaphor and becomes something you can pan, click, and ask questions of. **Graph Intelligence** is the agent that shares the canvas with you. You select; it reasons. You ask; the graph highlights. The conversation produces durable artifacts: Crystals, reports, persisted exploration sessions.
The Library answers *what do I know?* The Knowledge Graph answers *how does it connect, and what should I do with it next?*
## First useful action [#first-useful-action]
1. Open the **Graph** view from the sidebar. The overview shows your most-connected memories, entities, and Crystals.
2. Click any node, or run **Compute** to detect topic communities and color the graph by cluster.
3. When two Memory nodes should be read together, use **Connect memories** to create a [Memory Link](/docs/concepts/memory-links): name the relation, add a reason, and keep that connection in the graph.
4. Open the **Chat** tab in the right panel and ask one real question about what you're looking at. *"What is this cluster about?"* *"Where does this contradict itself?"* *"Find the shortest path between these two."*
The agent reads your selection, calls the right tools, and writes the answer on the same canvas. You should be able to answer a real question about your own knowledge without leaving the graph.
## Two ways to use the graph [#two-ways-to-use-the-graph]
### Visually, on your own [#visually-on-your-own]
Your knowledge as an interactive network. Drag to pan, scroll to zoom, click a node to inspect its details and edges. The timeline slider filters by date so you can watch a domain grow over weeks or months. Hold Cmd/Ctrl to multi-select; switch to lasso mode to draw a region. **Compute** runs Louvain community detection and colors the graph by cluster, so the topic structure becomes visible instead of buried under 1,000 dots. When you spot a relationship the system should remember, connect two Memory nodes directly. That edge becomes part of the graph, not just a note in your head.
The overview also renders in 3D — orbit the whole graph like a terrain, with communities as constellations and influence as elevation:
### With the Graph Intelligence Agent [#with-the-graph-intelligence-agent]
The Chat tab opens a reasoning partner that shares your canvas. When you select something, the agent reads the same selection. Its tool calls light up the graph in real time, so you can audit its reasoning while it works.
Useful question patterns:
* Ask *"What is going on here?"* with a community selected. The agent summarises the cluster's central themes and hands you back a list of the strongest sources.
* Ask *"Where does this contradict itself?"* with a topic, entity, or memory selected. The agent walks the EVOLVES chain and surfaces the disagreements.
* Multi-select two nodes and ask *"Find the shortest path between these two."* The agent walks the graph and explains every hop, often via bridge entities you wouldn't have spotted.
* Ask *"Draft a brief from this."* with a cluster selected. The agent produces a Crystal or a report. You decide whether to keep it.
## What makes this not "AI chat with a graph backend" [#what-makes-this-not-ai-chat-with-a-graph-backend]
A few architectural decisions add up to a different kind of product.
**Frozen context, single source of truth.** When you send a message, the agent sees the exact graph state you were looking at. No drift, no split-brain, no state mirror to keep in sync. You move the canvas while the agent thinks; that just means the next turn picks up the new view. The conversation thread itself is the source of truth.
**Visual reasoning chain.** Every tool the agent calls can emit a canvas command: `highlight_nodes`, `highlight_path`, `select_community`. You see the agent's reasoning as it happens, not as a black-box answer. If the agent says "the path goes through these three bridges", those three bridges are already lit up on the canvas.
**Artifacts that fit your existing surfaces.** When the agent produces a Crystal, that Crystal is a real Memory with `is_crystal=true`. When it produces a report, that report is a real Source in the Library. There are no new entity types to learn. Anything the agent saves is searchable, linkable, and editable from the same surfaces you already know.
**Step-based history.** Every turn captures both the user's frozen graph context and the agent's emitted canvas commands as message metadata. You can replay an exploration, resume it later, or share it. The conversation is not just a chat log; it is a complete record of an investigation.
## What the agent can do [#what-the-agent-can-do]
Twenty or so specialised tools, grouped by what they answer for you:
* **Navigate the graph.** Shortest paths between concepts, walks across `RELATES_TO` edges with their temporal context, batch-lookup of selected node details, neighbor traversal, community membership.
* **Find evidence.** Source memories behind a Crystal or entity, the EVOLVES chain showing how a piece of knowledge changed, the source documents that ground a claim, the past threads where you explored a topic.
* **Analyze structure.** Subgraph PageRank for centrality, bridge entities that connect communities, community summaries with member counts and key entities.
* **Synthesize and save.** A Crystal that distils 3+ source memories into a stable reference page (with `[[Entity Name]]` wikilinks already woven in), or a longer report or blog draft that lands in the Library and re-enters the search index.
You don't pick the tool; you ask the question and the agent picks. What we expose to you is the discipline: every claim it makes is traceable to memories, sources, or threads you can open. Crystals require three or more independent sources. Reports cite their evidence.
## From the Library, with Investigate [#from-the-library-with-investigate]
Most of the time you won't start in the Graph view. You'll be reading the [Library](/docs/library) when something raises a real question. Click **Investigate** on any wiki page (entity, crystal, or topic). The Graph view opens with that node already selected, or, for a topic, with every entity in the cluster highlighted at once. The Graph Intelligence chat shows an "Investigating topic: \" banner above the input, and any Crystal it creates from that session carries the cluster as its anchor.
That handoff is the loop: read in Library, dig in Graph, save back to Library.
## Boundaries [#boundaries]
A few things stay out of your way on purpose.
* The agent only proposes. Crystals and reports it produces show up as artifacts in chat. You decide what to keep.
* The agent reads the same canvas you do. There is no hidden context. If you cannot see it, neither can the agent.
* Graph Intelligence runs through your configured Remote LLM. Set it in **Settings > LLM Providers**.
* A heavy run produces tokens. Background and on-demand work share separate budgets and rate limits, configurable in **Settings > Knowledge Processing**.
## Where to go next [#where-to-go-next]
* [LLM Wiki](/docs/concepts/llm-wiki): the model behind the Library wiki and the Library → Investigate → Graph Intelligence loop.
* [Memory Links](/docs/concepts/memory-links): how to connect two memories inside a space when they should be read together.
* [Library](/docs/library): the read-side surface where most Investigate sessions begin.
* [Background Intelligence](/docs/concepts/background-intelligence): the work that builds and maintains the graph in the first place.
* [Crystals](/docs/concepts/crystals): how stable reference pages are synthesised, and what the agent's `CreateCrystal` actually produces.
* [Building memory systems for AI agents](https://nowledge-labs.ai/blog/building-memory-systems-for-ai-agents): the long-form essay on the Super Knowledge Graph and what makes it more than a regular knowledge graph. The post also embeds the original Chinese-language talk recording.
# Library (/docs/library)
The Library is where your files become usable knowledge.
It is for source material that should stay whole: PDFs, reports, spreadsheets, slide decks, markdown notes, and code. Mem parses them, indexes them, and lets them work alongside your memories instead of living as isolated attachments.
Use the Library for source material you want to preserve whole. Use memories for the durable takeaways. A strong workflow is: import the document, ask grounded questions against it, then extract memories only when you want its knowledge to join your long-term memory graph.
Drop a 40-page architecture review into the Library. Ask in the Timeline: *"What does the review say about API rate limits?"* The answer cites page 12 of the document and a Redis decision you saved three months ago. Your documents and your memories search together.
The Library stores PDFs, spreadsheets, Word files, presentations, code, and other formats. Content is parsed, split into searchable segments, and indexed. Once a document is **Searchable**, it shows up everywhere you already think from:
* **AI Now**: ask about a file by name, topic, or question. AI Now searches the Library, reads matching passages, and cites them alongside your memories.
* **The Timeline Feed Agent**: the built-in background Agent that turns conversations into memories can now also reach into Library documents when a thread references one.
* **Graph Intelligence Agent**: when exploring your graph, Source nodes can be searched and read directly, so you can move from a cluster of related memories into the underlying document without leaving the canvas.
* **Connected AI tools via MCP**: Claude Code, Cursor, and any other MCP-aware client can call `query_sources`, `read_source_content`, `search_source_chunks`, and `analyze_source_data` to ground their answers in your actual files.
* **The `nmem` CLI**: terminal and script workflows can search, read, and analyze the Library with `nmem sources search`, `read`, `search-chunks`, and `analyze`. See [the CLI reference](/docs/cli).
## Reading the Library as a wiki [#reading-the-library-as-a-wiki]
In v0.8 the Library also reads as a wiki. The memories, sources, and Crystals you have been collecting now show up as topic pages, entity pages, and crystal pages, cross-linked so you can click your way through them.
Switch to the **Wiki** tab inside the Library to see your knowledge grouped by topic. Each card lists the concepts most-discussed in that cluster and a few Crystals that summarise them. Click a card to open its topic page, click an entity to open its wiki entry, click an `[[Entity]]` chip inside a Crystal to keep going.
When reading raises a real question, click **Investigate** on any wiki page. The Knowledge Graph opens with the right thing already selected: a single node for an entity or crystal page, the whole cluster for a topic page. From there you can pan, expand neighbours, or hand the selection to the Graph Intelligence Agent and ask what is actually going on.
For the underlying model (what the system maintains for you, what you stay in charge of), see the [LLM Wiki concept page](/docs/concepts/llm-wiki).
## Wiki Export [#wiki-export]
The Wiki tab has a Download button on its tab row. Click it and pick a format:
Both export your **whole knowledge graph**: topics, entities, crystals, your memories grouped by type (`memories/decision/`, `memories/procedure/`, and the rest), the reports and blog drafts the agent generated, your active skills, and a label index. They differ only in flavor:
* **Markdown wiki** is the Obsidian-style folder, cross-linked with the same `[[wikilinks]]` you see inside Mem. It opens directly in Obsidian, Logseq, or any markdown reader.
* **OKF bundle** is the vendor-neutral version in the [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf), an open spec for knowledge as markdown files. It links with standard markdown paths instead of wikilinks, follows the spec's frontmatter, and validates against the OKF reference tools. Pick it for an interoperable copy, or to hand your knowledge to another tool that reads OKF.
Both are plain markdown either reader can open, so the choice is just the link style and frontmatter. Re-export whenever you want a fresh copy. The export is a snapshot, not a sync target: edits you make outside Mem do not flow back automatically.
For more on the OKF format and how the export maps onto it, see [Open Knowledge Format (OKF)](/docs/concepts/open-knowledge-format).
## The First Useful Document [#the-first-useful-document]
If you are new, import one document you actually care about. Then ask one concrete question about it in the Timeline.
That is the core loop:
* add one real source
* ask one grounded question
* see the answer use both the document and your existing knowledge
That is enough for a first proof. Memory extraction can wait until this basic loop already feels useful.
## Supported Formats [#supported-formats]
| Format | Extensions | What Happens |
| ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **PDF** | .pdf | Native text is extracted with layout awareness; scanned pages can be read with a configured Vision model |
| **Word** | .docx | Parsed to text with image extraction, segmented, indexed |
| **Presentations** | .pptx | Slide content extracted with images, indexed |
| **Spreadsheets** | .xlsx, .csv | Parsed to markdown tables, indexed. Multi-sheet XLSX renders as tabs |
| **Markdown** | .md | Parsed and indexed directly |
| **Plain text** | .txt, .org | Indexed as-is |
| **Code** | .py, .js, .ts, .rs, .go, .java, .c, .cpp, .rb, .swift | Indexed |
| **URL** | .html, .pdf | Converted to markdown, indexed |
## Adding Documents [#adding-documents]
Drag files into the Timeline input, or use the Library view to import. You can also drag entire folders: all supported files inside will be imported automatically.
Documents go through a processing pipeline:
1. **Parsing**: content extracted from the file format
2. **Segmentation**: split into searchable chunks
3. **Indexing**: added to both vector and keyword search indexes
Processing status is visible in the Library view. Once indexed, the document is **Searchable**, ready to use in conversations, global search, and connected AI tools.
### Adding web pages [#adding-web-pages]
Paste a public URL into the Timeline or Library and Mem will try to read it locally first. For many articles, docs pages, PDFs, and blogs, that is all it needs.
Some modern pages block basic fetching or only return an empty app shell. If you enable **Settings → Processing → Public web fallback**, Mem can ask Firecrawl to return clean public content for those pages. This is optional, and it only applies to safe public URLs. Mem does not send cookies, browser sessions, or signed-in pages to Firecrawl.
Use the browser extension for supported web AI chats. Use Browse Now with Chrome, Edge, Arc, or another Chromium browser for pages that need browser control: logged-in workspaces, private docs, paywalled pages, dashboards, or anything that only you can see.
For scanned PDFs, Mem first finishes the normal import so the app stays responsive. If a page has no text layer, Mem can read the scanned text in the background with the effective Vision model and add it back into the document.
Vision uses your **Default** provider unless you choose a separate model in **Settings → Providers → Vision**. Make sure the effective Vision model supports image input. If it does not, or your background budget is reached, the Library pauses the work and shows what to do next. After setting the model, return to the source and click **Continue**.
## Searchable, Study, and Extract Memories [#searchable-study-and-extract-memories]
Library has three different actions:
| Mode | What it means | How it happens |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **Searchable** | Content is parsed, segmented, and indexed. AI can read and reference the document when you ask about it in the Timeline. A document can stay searchable-only; it is not waiting for extraction. | Automatic, happens when you import a file. |
| **Study with AI** | A guided reading session. The AI reads the source, compares it with existing memories, and proposes what may be worth saving. Nothing is written unless you choose to save it. | Opt-in: click **Study with AI** on a source. |
| **Memories extracted** | A full extraction pass creates structured memories, graph links, and cross-references. The document's durable takeaways join your memory graph. | Opt-in: click **Extract memories** on a source. |
Asking about a file in the Timeline reads its content directly. Studying a file with AI helps you decide what matters. Extracting memories turns selected knowledge into persistent graph-backed memory.
### What memory extraction produces [#what-memory-extraction-produces]
When you extract memories from a source, the AI analyzes the content (computing statistics for spreadsheets, reading text for documents) and creates:
* **Memories**: 2-5+ atomic insights per document (decisions, facts, procedures), each searchable on its own
* **Graph connections**: links to your existing related memories, surfacing relationships you might not have noticed
* **Crystals**: synthesized crystals when 3+ memories cluster around a topic
* **Contradiction detection**: flags conflicts with existing knowledge (e.g., a new policy that reverses a previous decision)
Memory extraction uses AI processing time. The result count appears in the pipeline indicator after completion (for example, "Memories (5)").
## Searching Documents [#searching-documents]
Documents are searched alongside memories. A Timeline question like *"What does the Q4 report say about churn?"* searches both your saved memories and any imported documents that match.
In the Library view, you can filter by status (**Searchable**, **With memories**, **Stale**, or **Error**) to find sources by processing state. Searchable-only documents are normal; choose extraction when you want durable memories from them.
If you manage many documents for customers, projects, or internal workflows, add labels or source metadata when you import them. API, MCP, and CLI searches can then narrow the Library before ranking results. For example:
```bash
nmem sources search "renewal terms" --label customer-acme --metadata purpose=contract-review
nmem sources list --metadata material_type=case-study
```
Use labels for broad buckets people recognize. Use metadata for fields scripts and integrations already know, such as `customer`, `project`, `material_type`, or `purpose`.
## Chat with Your Documents [#chat-with-your-documents]
Ask questions about any document directly in the Timeline. The answer draws from both the document and your memories, citing specific pages.
*"What does the architecture review say about API rate limits?"* returns an answer referencing page 12 of the document and your Redis decision from three months ago.
## Batch Actions [#batch-actions]
Select multiple documents in the Library view and:
* **Send to AI Now** for cross-document analysis: compare reports, synthesize findings, or ask questions that span multiple documents
* **Extract memories**: select sources that do not yet have memories and click "Extract memories (N)" to process them together. For sources that already have memories, the button shows "Re-analyze (N)" to refresh their extracted knowledge
## Documents, Memories, and Threads [#documents-memories-and-threads]
Three types of content, each with its own purpose:
| Type | What it is | Example |
| ------------ | ------------------------------------ | ----------------------------------------- |
| **Memory** | An atomic insight, decision, or fact | "We chose PostgreSQL for jsonb support" |
| **Document** | Reference material imported whole | A 40-page architecture review PDF |
| **Thread** | An AI conversation archive | Your ChatGPT session about async patterns |
Documents and threads are sources. Memories are the distilled knowledge. When you extract memories from a document or thread, individual insights get saved as memories and connected to the knowledge graph. The original stays in the Library or Threads view as the source.
## Next Steps [#next-steps]
* **[Getting Started](/docs/getting-started)**: The Timeline and all ways to add knowledge
* **[Background Intelligence](/docs/advanced-features)**: How imported knowledge connects to your graph
* **[Search & Relevance](/docs/search-relevance)**: How search ranks results across memories and documents
# LLM Providers (/docs/llm-providers)
Choose your setup in three layers:
* **Plan or subscription**: what account or bundle you already pay for
* **Provider or endpoint**: where requests actually go
* **Model**: the concrete tool-capable default you run day to day
Then configure it once in Settings (or `nmem` CLI/TUI).
Follow [Use Nowledge Mem with fully local models](/docs/fully-local-models) for LM Studio and Ollama setup, purpose routing, verification, and privacy boundaries.
Nowledge Mem recommends **subscription-based defaults** for the smoothest daily experience right now:
* **OpenAI ChatGPT/Codex subscription**
* **Kimi Code subscription**
* **SuperGrok subscription**
For day-to-day AI Now usage, prioritize **fast tool-capable models** over SOTA by default.\
For ChatGPT/Codex, fetch the current model list in Settings and choose a supported Codex or base GPT-5 model. Kimi Coding Plan models are also good daily defaults.
If your current setup is spending too many tokens (for example always running `gpt-5.3-codex`), switch to a lighter tool-capable default first.
## What To Choose [#what-to-choose]
Best default for coding-heavy AI Now workflows with strong tool use support.
Great for coding workflows and tool-calling in AI Now.
Use your Grok subscription through xAI sign-in, without pasting an API key.
## Provider Guides [#provider-guides]
OpenAI (ChatGPT/Codex)
Best for:
coding + daily assistant workflows.
Stable tool-calling in AI Now and agents
Strong ecosystem compatibility
For ChatGPT Subscription, pick Codex models or base GPT-5 releases. Avoid chat aliases like
gpt-5-chat-latest
here.
Kimi / Moonshot
Best for:
Kimi Code subscription users.
Great fit for coding-heavy AI Now sessions
Reliable tool workflows in day-to-day usage
Anthropic Claude
Best for:
reliable autonomous workflows.
Strong planning and tool use quality
Good for long multi-step sessions
DeepSeek
Best for:
cost/performance-sensitive workflows.
Start with
deepseek-v4-flash
for AI Now and agents
Use
deepseek-v4-pro
when quality matters more than speed
OpenRouter
Best for:
one endpoint with many models.
Flexible multi-model routing
Pick tool-capable models for AI Now / agent workflows
Gemini
Best for:
Google ecosystem users.
Supported in AI Now and agent flows
Smooth fit with Google AI Studio credentials
xAI
Best for:
xAI API users.
Supported with tool workflows in AI Now
Use this path when you have an xAI API key
Use SuperGrok instead when you want to sign in with your Grok subscription
SuperGrok
Best for:
Grok subscription users.
Sign in with xAI from Settings; no API key paste is needed
Works in AI Now and agent workflows after the local OAuth token is saved
Keep using the xAI provider if you prefer API-key billing
MiniMax
Best for:
users already invested in MiniMax.
Supported in AI Now and extension workflows
Works with current MiniMax chat models
Z.AI
Best for:
Zhipu ecosystem users.
Supported for AI Now and agents
Good regional/provider fit for existing usage
Ollama
Best for:
local-first and self-hosted users.
No cloud dependency for model runtime
Use tool-capable models for AI Now agents
LM
LM Studio
Best for:
local OpenAI-compatible models with a desktop model manager.
Default local URL:
[http://127.0.0.1:1234/v1](http://127.0.0.1:1234/v1)
The API key is optional unless you enable authentication
In remote mode, LM Studio must run on the Nowledge Mem server machine
LM
Lemonade
Best for:
local Windows GPU workflows and Lemonade users.
Use the Lemonade provider instead of a generic custom endpoint
Default local URL:
[http://127.0.0.1:13305/v1](http://127.0.0.1:13305/v1)
AI Now can also use Lemonade's HTTP MCP endpoint when you add it as a custom MCP server
GitHub Copilot
Best for:
Copilot subscription workflows.
Supported in AI Now
Low-friction if your team already uses Copilot
API
OpenAI-Compatible Custom Endpoint
Best for:
private gateways and enterprise proxies.
Requires OpenAI-compatible chat completions
Tool support depends on your gateway/model
Use `deepseek-v4-flash` for the quickest DeepSeek setup in AI Now and agent tasks. Choose `deepseek-v4-pro` when you want the stronger V4 model. `deepseek-chat` still works, but `deepseek-reasoner` is not offered for agent workflows because it does not support tool calling.
## Context Window [#context-window]
Every model has a maximum number of tokens it can process in a single request. Nowledge Mem auto-detects this limit from the model name. For example, `gpt-4o` defaults to 128k tokens, `gemini-2.0-flash` to 1M.
You can override the context window in **Settings → Providers → Advanced** (or via `nmem config provider set --context-window `).
**When to adjust:**
* **Small or fine-tuned models** (8k–32k context): set the actual limit so that AI Now compacts the conversation before it overflows.
* **Extended-context models** (500k–1M+): increase the window so AI Now uses the full capacity instead of compacting early.
* **Custom or self-hosted models**: if the model name doesn't match a known pattern, the default is 128k. Set the real value to get accurate compaction behavior.
When a conversation approaches the context limit, AI Now automatically summarizes older messages and keeps the most recent exchanges. This lets long sessions continue without losing important context. Setting the right context window ensures compaction fires at the right time, not too early, not too late.
## Custom Provider Guidance [#custom-provider-guidance]
If you configure a custom OpenAI-compatible endpoint (`openai_compatible`) for DeepSeek V4, use `deepseek-v4-flash`, `deepseek-v4-pro`, or the exact DeepSeek V4 model id your gateway exposes. DeepSeek V4 uses a provider-specific thinking mode; Mem disables that mode during tool-loop agent calls so tool history remains compatible with strict DeepSeek validation.
If you run DeepSeek V4 through OpenRouter, keep using the OpenRouter provider. Mem leaves OpenRouter-hosted models on OpenRouter's own request contract instead of adding DeepSeek-native `thinking` fields.
Custom endpoints also support the newer **Responses API** (`/v1/responses`) alongside the legacy Chat Completions format. Select the API format when adding or editing the provider.
For Linux headless deployment setup, see [Linux Server Deployment](/docs/server-deployment).
# Mem Lifetime Pro (/docs/mem-pro)
## Free, Plus, Max, And Lifetime Pro [#free-plus-max-and-lifetime-pro]
Nowledge Mem offers **Free**, **Plus**, **Max**, and **Lifetime Pro** options.
**Free** is for trying Mem locally. You can sign in, save up to 50 memories, and use your own AI keys.
**Plus** is the account service plan. It includes monthly Nowledge AI credit, one managed Nowledge Link host, and future account features such as encrypted backup and selective sync. Your Mem data still stays on your machine unless you choose an account feature that uploads encrypted data.
**Max** is the upcoming higher-usage service tier for more included AI credit, larger backup capacity, premium model lanes, and team-oriented controls.
**Lifetime Pro** is different from Plus. It is a one-time local unlock: unlimited local memories, BYOK AI, three local desktop activations, and local app features for life. It does not include Nowledge AI credit, managed Nowledge Link, encrypted cloud backup, or cross-device sync.
For detailed feature comparisons, visit the [Pricing Page](https://mem.nowledge.co/pricing).
## Activating Lifetime Pro [#activating-lifetime-pro]
### Start checkout from the pricing page [#start-checkout-from-the-pricing-page-step]
Visit the pricing page and choose **Lifetime Pro** to proceed to checkout:
### Complete payment [#complete-payment-step]
Complete the payment using your email address.
Your email address will be used to receive the license key and is permanently associated with your Lifetime Pro activation.
### Receive your license key [#receive-your-license-key-step]
You'll receive an email with your license key.
You can retrieve your license key anytime at mem.nowledge.co/licenses using your email address.
### Open Plans in the app [#open-plans-in-the-app-step]
Open Nowledge Mem and navigate to **Settings** → **Plans**:
### Activate with your license key [#activate-with-your-license-key-step]
Paste your license key, then click **Activate License**:
### Confirm Lifetime Pro is active [#confirm-lifetime-pro-is-active-step]
Once activated, your Lifetime Pro status will be displayed:
Manage your activated devices anytime at mem.nowledge.co/licenses.
Need help? Contact [hello@nowledge-labs.ai](mailto:hello@nowledge-labs.ai) for assistance with activation or licensing.
# Memories (/docs/memories)
A memory is one durable thing worth keeping: a fact, preference, decision, plan, procedure, learning, event, or important context. Each memory should stand on its own, readable without the full conversation that produced it.
Memories are the core unit of Nowledge Mem. Search, the knowledge graph, crystals, daily briefings, and connected tools all become more useful because memories exist underneath them.
Use a memory for the durable takeaway. Use a thread when you need the original conversation history. A strong workflow is: save or import the thread, then distill the parts worth keeping into memories.
## The First Useful Memory [#the-first-useful-memory]
If you are new, do not overthink structure first. Save one real thing such as:
* a decision you made
* a lesson you learned
* a workflow you repeat
Then ask for it back in the Timeline. Once that works, this whole page becomes much easier to understand.
## Anatomy of a Memory [#anatomy-of-a-memory]
| Field | What it is |
| -------------- | ----------------------------------------------------------------------------------- |
| **Title** | A short summary. Auto-generated when you capture from the Timeline, or set manually |
| **Content** | The knowledge itself. Markdown supported |
| **Type** | What kind of durable knowledge this is |
| **Labels** | Categories for filtering and organization |
| **Importance** | A score from 0.1 to 1.0 that affects search ranking and briefing priority |
| **Created** | Timestamp. Used for temporal search and knowledge evolution tracking |
### Importance Scale [#importance-scale]
| Range | Meaning | Examples |
| --------- | ---------- | ----------------------------------------------------------------------- |
| 0.8 – 1.0 | Critical | Architectural decisions, breakthrough discoveries, production incidents |
| 0.5 – 0.7 | Useful | Standard decisions, good insights, project learnings |
| 0.1 – 0.4 | Background | Reference info, minor details, casual notes |
The default is 0.5. AI tools and background intelligence use this score to prioritize what surfaces in search results and daily briefings.
### Memory Type [#memory-type]
Each memory has one primary type. This helps agents decide how to use it:
| Type | Use for |
| ------------ | ------------------------------------------------ |
| `fact` | Durable reference information |
| `preference` | User taste, style choices, working constraints |
| `decision` | Choices with rationale and trade-offs |
| `plan` | Future intent, next steps, roadmap items |
| `procedure` | How-to knowledge, workflows, step-by-step guides |
| `learning` | Lessons, realizations, debugging conclusions |
| `context` | Background information that frames future work |
| `event` | Things that happened, outcomes, dated moments |
If an agent does not pass a type explicitly, Mem classifies the memory during creation. Connected tools should still pass the type when they know it, because a clear `decision` or `procedure` is more useful than a generic note.
### Labels [#labels]
New memories are labeled automatically when created. The system assigns 2–4 labels based on content and reuses your existing labels to keep the taxonomy consistent. You can always edit, add, or remove labels afterward.
You can also create custom labels. Labels are lowercase and hyphenated (`api-design`, `team-standup`). Filter by label in the Memories view to focus on a specific domain.
## Creating Memories [#creating-memories]
### In the Timeline [#in-the-timeline]
Type into the input at the top and press Enter. AI classifies your intent automatically:
* A thought becomes a **memory** with auto-generated title and labels
* A question gets **answered** from your existing knowledge
* A URL gets **fetched**, parsed, and indexed
* A file gets **parsed** and stored
See [Getting Started](/docs/getting-started) for the full onboarding walkthrough.
### From AI Conversations [#from-ai-conversations]
The [browser extension](/docs/integrations/browser-extension) captures memories from supported web AI chat platforms:
* **Auto-Capture** monitors conversations and saves what matters autonomously
* **Manual Distill** lets you trigger capture on a specific conversation
### From Threads [#from-threads]
Import a conversation, then distill it into individual memories. Each extracted memory gets its own title, labels, and importance score. This is how hours of AI conversation become searchable, connected knowledge. See [Threads](/docs/threads) for the full workflow.
### From AI Tools [#from-ai-tools]
Connected agents can read, search, and preserve durable knowledge while you work. The exact behavior depends on the connector path you chose:
| Integration | How memories are saved | Setup |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Dedicated connectors** (Claude Code, Grok Build, Codex, Gemini CLI, OpenClaw, Hermes Agent, Alma, Cursor, Droid, OpenCode, Copilot CLI) | Dedicated package teaches the agent when to recall, distill, add, and sometimes update memories | [Connectors](/docs/integrations) |
| **Reusable workflow packages** (`npx skills`, OpenCode, many agents) | Shared skills or prompts call `nmem` on your behalf | [Getting Started](/docs/getting-started) |
| **Direct MCP** (any MCP client without a dedicated package) | Agent calls `memory_add` and `memory_update` directly | [Connectors](/docs/integrations) |
The best-integrated setups do more than expose `memory_add`: they also teach the agent when to search first and when to update an existing memory instead of creating a duplicate.
### Via CLI [#via-cli]
```bash
# Add a memory with auto-generated title
nmem m add "We chose PostgreSQL for the new service because of jsonb support"
# Add with explicit title and labels
nmem m add "PostgreSQL chosen for jsonb support and team familiarity" \
--title "Database Decision: PostgreSQL" \
--unit-type decision \
--labels "decision,infrastructure" \
--importance 0.8
```
### Via API [#via-api]
```bash
curl -X POST http://127.0.0.1:14242/memories \
-H "Content-Type: application/json" \
-d '{
"content": "We chose PostgreSQL for the new service",
"title": "Database Decision",
"unit_type": "decision",
"labels": ["decision", "infrastructure"],
"importance": 0.8
}'
```
See the [API Reference](/docs/api) for the full schema.
## Searching Memories [#searching-memories]
### In the App [#in-the-app]
Open memory search with Cmd + K (macOS) or Ctrl + K (Windows/Linux). Three search modes work together:
* **Semantic** finds memories by meaning, so searching "design patterns" finds memories about "architectural approaches"
* **Keyword** does exact match for specific terms
* **Graph** discovers memories through entity connections and topic clusters
Press Cmd + Shift + K from any application to search without opening Nowledge Mem.
### From AI Tools [#from-ai-tools-1]
Connected agents search through their native connector, shared workflow package, or MCP tools. When a topic might connect to prior work, the strongest paths search your knowledge base without waiting for an explicit prompt.
### Via CLI [#via-cli-1]
```bash
# Semantic search
nmem m search "authentication patterns"
# Narrow by metadata your workflow already knows
nmem m search "renewal decision" --metadata customer=acme --metadata purpose=contract-review
# JSON output for scripting
nmem --json m search "API design" | jq '.memories[0].content'
```
Use metadata filters when an integration or import flow already knows a stable
field such as `customer`, `project`, `material_type`, or `purpose`. Mem narrows
the memory set before ranking, so the agent searches the right slice instead of
hoping broad ranking finds it.
## Editing and Organizing [#editing-and-organizing]
### Update a Memory [#update-a-memory]
Click any memory in the Memories view to edit its content, title, labels, or importance. Changes take effect immediately.
Via CLI:
```bash
# Update importance
nmem m update --importance 0.9
# Update labels
nmem m update --labels "decision,infrastructure,critical"
```
### Delete a Memory [#delete-a-memory]
Delete from the memory detail view, or via CLI:
```bash
nmem m delete
nmem m delete -f # Use -f in scripts or non-interactive shells
```
`nmem m delete` asks for confirmation by default. In scripts, agents, or any non-interactive shell, add `-f` to avoid hanging while waiting for input.
## How Memories Connect [#how-memories-connect]
When [Background Intelligence](/docs/advanced-features) is enabled, memories grow connections automatically:
* **Knowledge Graph.** Every memory becomes a node. The system extracts entities (people, technologies, concepts) and maps relationships. Search "distributed systems" and find your memory about "Node.js microservices". The words don't match, the meaning does.
* **Knowledge Evolution.** Save something new about a topic you've written about before, and the system creates a version link: *replaces*, *enriches*, *confirms*, or *challenges*. Trace how your understanding of any topic changed over time.
* **Crystals.** When enough memories cover the same ground, they get synthesized into a reference article. Sources are cited. When you save related information later, the crystal updates.
* **Working Memory.** Each morning, Mem writes a briefing from your recent and important memories. The Default space keeps `~/ai-now/memory.md`; if you use [Spaces](/docs/spaces), other spaces get their own briefings too.
See [Background Intelligence](/docs/advanced-features) for the full guide on how these work.
## Where Memories Come From [#where-memories-come-from]
| Source | How | Learn more |
| ------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| Timeline | Type and press Enter | [Getting Started](/docs/getting-started) |
| Browser extension | Auto-capture or manual distill from web AI chats | [Browser Extension](/docs/integrations/browser-extension) |
| Thread distillation | Extract from imported AI conversations | [Threads](/docs/threads) |
| AI tools | Skills, plugins, or MCP `memory_add` | [Connectors](/docs/integrations) |
| CLI | `nmem m add` | [CLI Reference](/docs/cli) |
| API | `POST /memories` | [API Reference](/docs/api) |
## MCP Tools [#mcp-tools]
| Tool | What it does |
| --------------------- | --------------------------------------------------------------------- |
| `memory_search` | Search memories by meaning, keywords, or graph connections |
| `memory_add` | Create a new memory with content, title, type, labels, and importance |
| `memory_update` | Update content, title, importance, or labels |
| `memory_delete` | Delete one or more memories |
| `list_memory_labels` | List all labels with usage counts |
| `read_working_memory` | Read today's daily briefing |
## Next Steps [#next-steps]
* **[Threads](/docs/threads)**: Import and distill AI conversations into memories
* **[Library](/docs/library)**: Import documents alongside your memories
* **[AI Now](/docs/ai-now)**: Personal AI with full access to your knowledge base
* **[Background Intelligence](/docs/advanced-features)**: How memories grow connections automatically
* **[Browser Extension](/docs/integrations/browser-extension)**: Capture memories from web AI conversations
* **[Connectors](/docs/integrations)**: Connect your AI tools through native connectors, reusable packages, or MCP
# Nowledge FS (/docs/nowledge-fs)
Nowledge FS is Mem's preview path-first layer for humans, agents, and scripts.
In the app, people meet it as **Knowledge Tree**: everything you know appears in one familiar tree. Memories, conversations, wiki pages, Working Memory, activities, sources, and artifacts keep their native behavior. The tree is not a folder full of raw implementation files. It is a calm map over Mem itself, so you can open one thing, see the right preview, and keep moving.
Agents see the same map as a virtual filesystem. That is the important shift: a human can browse in the app, while a script or agent can list, read, search, recall, and update canonical writable objects by path.
This is the first public shape of Knowledge Tree and Nowledge FS. It is ready to try in the app, CLI, API, and MCP, but the mount, source-fragment, SQL/Cypher, replay, and tail phases are still being designed.
## When To Use It [#when-to-use-it]
Use Knowledge Tree when you want a sense of place.
* You remember that something exists, but not whether it was a memory, thread, wiki topic, or source.
* You want to scan by type, date, label, or topic without opening several different views.
* You want an agent to inspect nearby context before loading large objects.
* You want paths you can copy into a command, script, prompt, or MCP call.
If you are just asking one question, search is still fine. Knowledge Tree is for navigation, orientation, and controlled inspection.
## First Useful Loop [#first-useful-loop]
1. Open **Tree** in the app sidebar.
2. Open one branch such as **Memories**, **Threads**, **Wiki**, **Working Memory**, **Activities**, or **Artifacts**.
3. Click one item. The preview should feel like the rest of Mem: memories open as memory context, threads as readable conversations, wiki pages as wiki pages, and activities as Timeline-style events.
4. If you use the CLI, run:
```bash
nmem fs ls /
nmem fs recall "what did we decide about auth?" --in /memories -k 5
```
A good result is not a long blob of text. It is a path you can inspect next:
```bash
nmem fs stat /memories/by-id/.memory.md
nmem fs cat /memories/by-id/.memory.md
```
## How To Think About Paths [#how-to-think-about-paths]
Paths are Mem addresses, not files on your disk.
```text
/memories/by-id/.memory.md
/threads///messages.jsonl
/wiki/entities/.entity.md
/working-memory/today.md
/feed/2026-05-15/.feed.jsonl
/artifacts/imports/.artifact.pdf
```
Some paths are canonical. Those can be updated when the object itself is writable. Other paths are aliases, like a memory shown under a label or date branch. Aliases are there for browsing and should be edited through the canonical path.
## What Agents Should Do [#what-agents-should-do]
Agents should move through the tree in small steps:
1. Use `recall` for fuzzy memory questions.
2. Use `find` for structural constraints such as type, label, date, or mention.
3. Use `grep` for exact phrases, or `grep -E` for explicit regex.
4. Use `stat` before loading large objects.
5. Use `cat` only after a useful path has been found.
This keeps context small and makes the agent's work inspectable. You can see the same path in the app, the CLI, the API, or the MCP tool.
```bash
nmem fs recall "why did we change token refresh?" --in /memories -k 5
nmem fs ls /memories/by-label/auth
nmem fs cat /memories/by-id/.memory.md
```
For long conversations and documents, agents should not load the whole file first. Search the branch, then read a small line window:
```bash
nmem fs grep "JWT rotation" /threads
nmem fs cat /threads///messages.jsonl --line 42 --lines 12
nmem fs grep "rate limit" /sources
nmem fs cat /sources/.pdf --line 120 --lines 80
```
Thread transcripts are JSONL: one line is one message. Parsed Library documents are rendered as markdown, so grep line numbers can be passed directly into `cat --line`. Grep is case-insensitive fixed-string search by default; use `--case-sensitive` for exact casing, and `-E` when you need regex alternation such as `JWT|token`.
In this preview, `recall` is memory-backed. Use `grep` for exact search inside threads and parsed Library documents.
MCP clients can use the same verbs through `mem_fs`. Codex, Claude, Cursor, Gemini, OpenClaw, and other agents are just consumers of this shared Mem shape; no single integration owns it.
The concrete entry points keep short host-friendly names: `nmem fs` in the CLI, `/fs/*` in the API, and `mem_fs` in MCP.
For tools and adapters, start by asking Mem what this server supports:
```bash
nmem fs capabilities --json
```
The response includes the current roots, verbs, limits, and feature flags. That keeps integrations from guessing whether a future surface such as mounting, source fragments, SQL, Cypher, replay, or tail has shipped yet.
## What Not To Worry About Yet [#what-not-to-worry-about-yet]
* You do not need to mount anything.
* You do not need to understand the graph schema.
* You do not need to choose between Tree and Library. Library remains the rich document and wiki reading surface; Tree gives you one map across all Mem objects.
* You do not need SQL or Cypher for the preview release. Those query surfaces belong to later phases after the safety limits and result shapes are pinned.
## Success Check [#success-check]
Knowledge Tree is working when:
* the app shows the main branches without raw implementation files;
* clicking an item opens a native Mem preview, not a generic text dump;
* `nmem fs ls /` returns the same top-level idea as the app;
* `nmem fs recall ...` returns paths;
* web and remote clients can use the same `/fs/*` API shape as desktop.
## Next [#next]
Run `nmem fs` from a terminal or script.
Build against the `/fs/*` endpoints directly.
Pick the native connector or MCP path for your tool.
Use Library when you want the richest document and wiki reading experience.
# Your Profile (/docs/profile)
Your profile is how Mem's agents understand you. Without it, they work generically. With a few sentences, every briefing, label, and insight becomes more relevant to your actual work.
## What Your Profile Does [#what-your-profile-does]
When you fill in your profile, every agent in the system reads it:
* **Daily briefings** frame what matters around your role and current work
* **Auto-labeling** picks categories that match how you think, not generic taxonomy
* **Knowledge extraction** understands domain terms you use
* **AI Now** starts each session knowing your context
You fill it in once. Every agent reads it every time it runs.
## Setting Up Your Profile [#setting-up-your-profile]
### Open Profile [#open-profile-step]
Go to **Context → You**.
### Name and Aliases [#name-and-aliases-step]
Your name helps agents recognize you in imported conversations and threads. Aliases are handles you use on other platforms (GitHub username, Twitter handle, Slack display name). Agents use these to identify which messages are yours when processing threads from different sources.
### About You [#about-you-step]
A few sentences about your role, current work, and interests. This is the most impactful field. Agents use it to decide what matters when they process your knowledge.
Good examples:
* *Product designer at a fintech startup, focused on mobile payments and onboarding flows*
* *Currently building a knowledge base for our compliance team to reduce repeated legal reviews*
* *Interested in AI-assisted writing, second brain methodology, and personal knowledge management*
You don't need to write all three. Even one sentence changes how agents prioritize.
### Custom Instructions [#custom-instructions-step]
Rules for how agents handle your knowledge. This is where you tell agents what to do differently from their defaults.
Examples:
* **Labels**: *"Always label memories about customer feedback with 'customer-voice'. Use project codenames, not full project names."*
* **Language**: *"Write briefings in French. Use technical English terms for programming concepts."*
* **Tone**: *"Keep briefings concise, no more than 5 bullet points. Skip obvious connections."*
Custom instructions are applied to daily briefings, background knowledge processing, and AI Now sessions.
### Output Language [#output-language-step]
Choose the language agents use when they write briefings, insights, labels, and other generated content. This is separate from the app interface language.
The picker includes every official EU language, Norwegian Bokmål, Icelandic, and the existing global language set. The same choice follows you between local and Cloud workspaces.
## How It Reaches Your Agents [#how-it-reaches-your-agents]
Your profile is injected into three agent paths:
| Agent | What it reads | How it uses it |
| --------------------------- | ---------------------------------- | ------------------------------------------------------- |
| **Background Intelligence** | Full profile + custom instructions | Frames briefings, labels, and insights around your work |
| **Knowledge Agent** | Full profile + custom instructions | Guides EVOLVES detection, labeling, and extraction |
| **AI Now** | Full profile + custom instructions | Starts each session with your context already loaded |
Supported connected tools receive your profile through **Context** when they load the Context Bundle at session start. Simpler or older integrations may still benefit indirectly through better search results, labels, and briefings.
## Tips [#tips]
* **Be specific over comprehensive.** "Leading a MongoDB-to-PostgreSQL migration" is more useful than "senior software engineer with 10 years of experience."
* **Update when your work changes.** The profile is not a resume. If you switch projects, update it.
* **Custom instructions compound.** A rule like "always label with project codenames" saves you from manually relabeling hundreds of memories.
* **You can leave fields empty.** Agents fall back to generic behavior for any field you skip.
## Next Steps [#next-steps]
* **[Background Intelligence](/docs/advanced-features)**: See what agents do with your profile
* **[Context](/docs/ai-context)**: Check what each connected AI receives before it starts
* **[AI Now](/docs/ai-now)**: Your personal AI workspace, pre-loaded with your context
* **[Connectors](/docs/integrations)**: Connect the tools that benefit from better context
# Access Mem Anywhere (/docs/remote-access)
Nowledge Mem runs on your machine, so your data never leaves your control. Access Anywhere lets you reach that same instance from any other device, agent, or browser through a secure tunnel.
One Mem, many ways to connect: your laptop at a coffee shop, a browser tab on your phone, a coding agent on a CI runner, AI Now on a second desktop. The Mem on your always-on machine is the hub. Everything else connects to it.
This is also how sync works in Mem today: one always-on Mem instance, many connected clients. If you want the short product explanation first, read [Sync Across Devices](/docs/sync).
If you subscribe to Plus or Max, open **Settings → Access Anywhere** and turn on **Nowledge Link**. Mem creates the stable link for you; you do not need to own a domain or configure Cloudflare. The manual Quick link and Cloudflare account paths below remain useful for Lifetime Pro users, servers, and advanced BYO-domain setups.
Run Nowledge Mem on an always-on device, such as a Mac Mini, a Linux server, or a desktop that stays powered on. Then connect from everywhere else: a second laptop, a web browser, or the iOS mobile app. This gives you 24/7 access to your knowledge base, background intelligence that keeps running, and a single source of truth for all your tools and devices.
## Choose Your Connection Type [#choose-your-connection-type]
| Type | Best for | What URL you get |
| ---------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
| **Nowledge Link** | Plus and Max users who want one-click setup | Stable `*.nowledge-mem.com` URL |
| **Quick link** | Fast setup in under a minute | Random `*.trycloudflare.com` URL |
| **Cloudflare account** | Daily/long-term usage | Stable URL on your own domain (for example `https://mem.example.com`) |
## Before You Start [#before-you-start]
Open this guide from **Settings → Access Mem Anywhere → Guide**.
* Nowledge Link requires an active Plus or Max subscription and sign-in inside Nowledge Mem.
* Quick link needs no Cloudflare account and no domain.
* Cloudflare account mode requires a domain already managed in your Cloudflare account.
* If you do not have a domain in Cloudflare yet, use **Quick link** first.
* In Cloudflare account mode, the final public URL appears only after you create a hostname route.
If you are on a server/terminal workflow, open nmem tui → Settings tab → Access Anywhere.
You can configure stable link, start/stop tunnel, rotate/reveal key, and view terminal setup there.
Access Anywhere management APIs are local-only.\
If your shell is pointed at a remote Mem (NMEM\_API\_URL=https\://...), temporarily switch back to local ([http://127.0.0.1:14242](http://127.0.0.1:14242)) before configuring tunnel settings.
## Path A: Quick Link (No Account) [#path-a-quick-link-no-account]
### Open remote access in Mem [#open-remote-access-in-mem-step]
Open **Settings → Access Mem Anywhere**.
Turn on **Allow devices on same Wi-Fi** if you also want LAN access.
When you enable this, an API key is automatically generated. Other devices on your network will need this key to connect. It's the same key used for access anywhere. You can copy it from the **API Key** section that appears below.
### Choose Quick link and start [#choose-quick-link-and-start-step]
In **Access from Anywhere**, choose **Quick link**, then click **Start**.
Wait for status to become **Live**.
### Copy URL and API key [#copy-url-and-api-key-step]
In **Ready to connect**, copy:
* **URL**
* **API key**
Use **Rotate** if you want to issue a fresh key.
### Verify from another machine [#verify-from-another-machine-step]
```bash
export NMEM_API_URL="https://"
export NMEM_API_KEY="nmem_..."
nmem status
```
Expected: `status ok`.
Some VPS, office, campus, or ISP networks block UDP/QUIC. Mem now retries Cloudflare tunnel startup with HTTP/2 automatically if QUIC fails during startup.
If you want to force TCP-only transport in a headless or systemd deployment, set:
```bash
export TUNNEL_TRANSPORT_PROTOCOL=http2
```
Then restart Mem and start Access Anywhere again.
## Path B: Cloudflare Account (Stable URL) [#path-b-cloudflare-account-stable-url]
You need a domain already in Cloudflare DNS (for example `example.com`) before this path can produce a stable URL.
### Create a tunnel and copy the token [#create-a-tunnel-and-copy-the-token-step]
In Cloudflare Zero Trust:
1. Open Networks → Connectors → Create a tunnel.
2. Click Select Cloudflared.
3. Name the tunnel and click Save tunnel.
4. In **Install and run connectors**, Cloudflare shows a command like:
```bash
sudo cloudflared service install ...
```
You do not run that command. Mem runs the tunnel for you; you only need the token from it. Copy the token, then in Mem paste either:
* the raw token, or
* the full command line (supported forms: `service install `, `--token `, `--token=`).
Mem extracts the token automatically.
On the desktop app and `.deb` / AppImage host installs, Mem bundles its own `cloudflared`, so you never install or run it yourself. This is unchanged.
On the [Docker deployment](/docs/docker), `cloudflared` is now bundled in the image too (both the default and `:cuda` tags). Earlier guidance to install or run `cloudflared` as a separate sidecar in the container no longer applies: configure the tunnel from **Settings → Access Anywhere** or the in-container `nmem` CLI, and the server manages it.
### Create a public hostname route [#create-a-public-hostname-route-step]
In tunnel routing / hostname routes:
1. Create a hostname (for example `mem.example.com`).
2. Bind it to the tunnel you created.
This step creates your stable public URL.
### Map the hostname to local Mem API [#map-the-hostname-to-local-mem-api-step]
1. Open Networks → Connectors → your tunnel.
2. In Published application routes, click Add a published application route.
3. Map `mem.example.com` to your local Mem server:
* Subdomain: `mem`
* Domain: your Cloudflare-managed domain
* Service Type: `HTTP`
* Service URL: `http://127.0.0.1:14242`
Do not append `/remote-api`.
### Save and start in Mem [#save-and-start-in-mem-step]
Back in Settings → Access Mem Anywhere → Cloudflare account:
* Public URL: `https://mem.example.com`
* Tunnel token: paste raw token or full `cloudflared` command
Then:
* Click Save
* Click Start
* Click Rotate if you want a fresh key
* Click Copy to copy URL and API key
### Verify from another machine [#verify-from-another-machine-step-1]
```bash
export NMEM_API_URL="https://mem.example.com"
export NMEM_API_KEY="nmem_..."
nmem status
```
Expected: `status ok`.
## Use It on Other Clients [#use-it-on-other-clients]
Pick the connection path that matches your situation:
* **Mobile app**: native iOS or Android access from your phone or tablet
* **Desktop app**: full experience including AI Now from a second computer
* **Web browser**: quick visual access from any device
* **`~/.nowledge-mem/config.json`**: the shared local client config written by `nmem config client ...`, reused automatically by `nmem`, OpenClaw, Bub, Claude Code, and other integrations
* **Browser extension**: paste your URL + key in SidePanel settings
* **ChatGPT / OAuth MCP clients**: paste the public `/mcp` endpoint and approve Mem through OAuth
* **Direct MCP**: for MCP clients without a better dedicated path, or as the companion MCP layer for hybrid hosts like Codex
### Mobile App (iOS & Android) [#mobile-app-ios--android]
The mobile app is in alpha. iOS is available via TestFlight; Android is available as an unsigned APK. Reach out via [Discord](https://discord.gg/nowledge) for TestFlight access, or download the APK from the [community releases page](https://github.com/nowledge-co/community/releases/tag/v0.6.11).
The mobile app is a native wrapper that connects to your Mem server: no local database, no local Python backend. It gives you the full mobile experience: search, memories, threads, library, graph, and feed.
1. Install the app (TestFlight for iOS, APK for Android)
2. Enter your **Mem URL** and **API key**
3. Tap **Connect**
The app stores your credentials locally and reconnects automatically on subsequent launches.
### Desktop App (Client Mode) [#desktop-app-client-mode]
Install Nowledge Mem on a second computer and connect to your main instance:
1. Open **Settings → Access Anywhere**
2. Enter the URL and API key from your main Mem
3. Click **Connect**
You get the full desktop experience: search, memories, threads, library, graph, and **AI Now**. AI Now runs on the Mem server you connect to and uses that server's LLM configuration. No extra LLM setup is needed on the client.
The title bar shows **Remote** to indicate you're connected to another Mem. AI Now sessions, message history, and pasted images stay with that server so you can move between clients.
### Web Browser [#web-browser]
Open your Mem URL with `/app` appended (for example `https://mem.example.com/app`) in any modern browser.
Enter your API key to log in. You get search, memories, threads, graph views, and AI Now from the same server-backed session list.
This is the fastest way to check your knowledge base from a machine where you haven't installed the desktop or mobile app.
On mobile, the native app (above) is recommended. If you prefer the browser, tap **Share → Add to Home Screen** (iOS) or the install banner (Android) to save it as a shortcut. It opens full-screen without browser chrome.
### nmem CLI [#nmem-cli]
**Auto-configured on the same machine.** If you run `nmem` on the same computer as the desktop app, this file is created automatically when Access Anywhere generates an API key. You can skip straight to `nmem status`.
Configure this machine once so every `nmem` command, and every plugin that uses `nmem`, connects automatically:
```bash
nmem config client set url https://
nmem config client set api-key nmem_...
```
```bash
nmem status # reads from config.json
nmem m search "project notes"
```
The command writes the same local client config file that OpenClaw, Bub, Claude Code, Claude Desktop, and other integrations read. It is separate from `nmem config access ...`, which controls how a Mem server is exposed to other devices.
For CI or scripted setups, you can also use `NMEM_API_URL` and `NMEM_API_KEY` environment variables. Priority: CLI flags > env vars > config file > defaults.
### Browser Extension (Side Panel Or Sidebar) [#browser-extension-side-panel-or-sidebar]
Open any supported AI chat page, then open **Nowledge Mem Exchange** in the browser side panel or sidebar:
1. Click **Settings**
2. In **Access Mem Anywhere**, paste the terminal setup copied from Mem Desktop:
```bash
export NMEM_API_URL="https://"
export NMEM_API_KEY="nmem_..."
```
3. Click **Fill URL + key**
4. Click **Save**
5. Click **Test connection** (should show success)
You can also type URL + key manually in the same section.
### ChatGPT / OAuth MCP Clients [#chatgpt--oauth-mcp-clients]
Some cloud MCP clients, including ChatGPT Connectors, cannot use a private
`nmem_` API-key header. For those clients, use **Remote MCP over OAuth**:
1. In Mem, open **Connectors → AI Tools → Remote MCP over OAuth**.
2. Click **Start setup**.
3. Let Mem open the pairing page in the browser profile you will use for the AI
client's OAuth approval.
4. Copy the Access Anywhere MCP endpoint. It must end with `/mcp`.
5. Paste that URL into the AI client's MCP connector setup.
6. Approve Mem on the OAuth page in that same browser profile.
For ChatGPT, create the connector from ChatGPT Web settings. After it is
connected, the same connector is available in ChatGPT Web and the ChatGPT
desktop app; mention `@Nowledge Mem` in a chat when you want ChatGPT to search
Mem.
For ChatGPT screenshots, see [ChatGPT Web and Desktop](/docs/integrations/chatgpt-web).
### OpenClaw Plugin [#openclaw-plugin]
If you already ran `nmem config client ...` on this machine, you're done. The OpenClaw plugin reads the same shared client config automatically.
You can also set credentials in the OpenClaw dashboard under **Automation → Plugins → Nowledge Mem**.
The API key is passed to the `nmem` subprocess via environment variable only. It never appears in logs or process arguments. Behavioral skills bundled with the plugin (like the memory guide) work the same in remote mode; they're part of the plugin, not the server.
### Bub Plugin [#bub-plugin]
Same shared client config. If you already ran `nmem config client ...` on this machine, the Bub plugin picks those credentials up automatically.
```json title="~/.nowledge-mem/config.json"
{
"apiUrl": "https://",
"apiKey": "nmem_..."
}
```
Or set `NMEM_API_URL` and `NMEM_API_KEY` environment variables before running Bub.
### Alma Plugin [#alma-plugin]
Two options. Pick whichever fits your setup:
**Option A: Plugin settings (recommended)**
In Alma, open Settings and configure the Nowledge Mem plugin:
* **`nowledgeMem.apiUrl`**: your remote URL (e.g. `https://mem.example.com`). Leave empty for local.
* **`nowledgeMem.apiKey`**: your Mem API key (`nmem_...`). Passed via environment variable only, never logged or shown in process arguments.
The plugin shows `mode=remote` or `mode=local` in its activation log so you can confirm which mode is active.
**Option B: Environment variables**
Set these in your shell before starting Alma:
```bash
export NMEM_API_URL="https://"
export NMEM_API_KEY="nmem_..."
```
Both options are equivalent. Use Option A for a self-contained setup. Use Option B to keep credentials out of config files.
### MCP / Agent Nodes [#mcp--agent-nodes]
MCP clients connect via HTTP. The MCP host owns that connection, so it does **not** automatically read `~/.nowledge-mem/config.json`.
If you already configured this machine with `nmem config client ...`, generate the exact host config from the same URL and API key:
```bash
nmem config mcp show --host codex
nmem config mcp show --host gemini-cli
nmem config mcp show --host cursor
nmem config mcp show --host claude-desktop
```
Paste the generated block into that host's MCP settings. It includes your API key when one is configured, so keep it in the host's private user config.
If you are writing the block by hand, pass your API key in the `Authorization` header, or use the `X-NMEM-API-Key` header.
Use the exact MCP endpoint with a trailing slash: `https:///mcp/`.
**Cursor** (`~/.cursor/mcp.json` or workspace `.cursor/mcp.json`):
```json
{
"mcpServers": {
"nowledge-mem": {
"url": "https:///mcp/",
"type": "streamableHttp",
"headers": {
"APP": "Cursor",
"Authorization": "Bearer nmem_..."
}
}
}
}
```
or
```json
{
"mcpServers": {
"nowledge-mem": {
"url": "https:///mcp/",
"type": "streamableHttp",
"headers": {
"APP": "Cursor",
"X-NMEM-API-Key": "nmem_..."
}
}
}
}
```
**Claude Desktop.** If you use the [Nowledge Mem extension](/docs/integrations/claude-desktop), it reads the same shared client config as `nmem`:
* macOS / Linux: `~/.nowledge-mem/config.json`
* Windows: `%USERPROFILE%\.nowledge-mem\config.json`
```json
{
"apiUrl": "https://",
"apiKey": "nmem_..."
}
```
If you're running Nowledge Mem Desktop on the same machine, this file is usually written for you automatically when you start Access Anywhere.
Alternatively, add an MCP server entry to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"nowledge-mem": {
"url": "https:///mcp/",
"type": "streamableHttp",
"headers": {
"APP": "Claude",
"Authorization": "Bearer nmem_..."
}
}
}
}
```
**Codex** (`~/.codex/config.toml`, shared by the desktop app and CLI):
If you are following the dedicated [Codex guide](/docs/integrations/codex-cli), keep that plugin package in place. The package includes a local MCP endpoint by default. For remote Mem, run `nmem config mcp show --host codex` and paste the generated TOML into `~/.codex/config.toml`.
**Gemini CLI** (`settings.json`, override for the Gemini extension):
If you installed the [Gemini CLI extension](/docs/integrations/gemini-cli), the extension includes a local MCP endpoint by default. For remote Mem, run `nmem config mcp show --host gemini-cli` and paste the generated JSON into Gemini's user settings.
**Claude Code.** Install the [Nowledge Mem plugin](/docs/integrations/claude-code) for automatic Working Memory, search, and session capture. For remote mode, run `nmem config client set url ...` and `nmem config client set api-key ...` once on the client machine. The plugin's `nmem` commands read that same shared local config.
**CI / other shell-based agents.** Set `NMEM_API_URL` and `NMEM_API_KEY` environment variables. Same variables work in any shell context.
For transcript-backed saves such as `nmem t save --from claude-code`, `grok`, `gemini-cli`, or `codex`, remote mode does **not** mean the Mem server reads those agent session files remotely. The client machine running the agent still performs local discovery and parsing, then uploads the normalized thread data to Mem.
## Quick Health Check [#quick-health-check]
```bash
curl -H "Authorization: Bearer $NMEM_API_KEY" "$NMEM_API_URL/health"
```
Expected: health JSON response.
If wrong key:
```bash
curl -H "Authorization: Bearer wrong_key" "$NMEM_API_URL/health"
```
Expected: `401`.
If your proxy strips auth headers:
```bash
curl "$NMEM_API_URL/health?nmem_api_key=$NMEM_API_KEY"
```
## Security and Operations [#security-and-operations]
* API key is required for every remote request, both tunnel and LAN connections.
* When LAN access is enabled, connections from other devices on your network require the API key. Connections from the same computer are always allowed without a key, unless you enable **Require API key on localhost** in Settings.
* Rotate key anytime in Settings (old key becomes invalid immediately).
* After your first successful **Start**, tunnel reconnects automatically on app restart until you click **Stop**.
* Browse-Now / Browser Bridge automation endpoints are local-only and are not exposed through Access Anywhere.
* Stop tunnel when remote access is not needed.
## Troubleshooting [#troubleshooting]
* **Start timed out**: your network/proxy may block Cloudflare traffic. Retry, or switch to Cloudflare account mode.
* **`401 Missing API key`**: proxy likely removed auth headers. Update `nmem`, or use query fallback for manual checks.
* **`429 Too many invalid auth attempts`**: wrong key was retried repeatedly. Re-copy key or click **Rotate**.
# Search & Relevance (/docs/search-relevance)
How Nowledge Mem finds matching memories, ranks them by relevance, and learns from your usage patterns.
## The Scoring Pipeline [#the-scoring-pipeline]
Search combines multiple signals to rank results beyond keyword matching.
### Semantic Scoring [#semantic-scoring]
This track finds memories that match what you're looking for:
* **Meaning-based search**: Finds memories by semantic similarity, not just exact words. Search for "design patterns" and find memories about "architectural approaches."
* **Keyword search**: Catches exact phrases and technical terms using BM25 ranking.
* **Label matching**: Surfaces memories with matching tags.
* **Graph traversal**: Discovers connected memories through entities and topic communities.
### Decay, Confidence & Temporal Scoring [#decay-confidence--temporal-scoring]
This track adjusts results based on freshness, validation, and your usage:
* **Recency**: Recently accessed memories score higher. We use exponential decay with about a 30-day half-life.
* **Frequency**: Memories you access repeatedly become more durable (logarithmic scaling with diminishing returns).
* **Importance floor**: High-importance memories maintain minimum accessibility even when unused.
* **Confidence**: Memories that have been validated through usage and knowledge-graph connections get a subtle boost. Confidence grows with evidence and never decreases.
* **Temporal matching**: Boosts memories whose event time matches your query (deep mode only).
These tracks combine into a final score that determines result ranking.
## Memory Decay [#memory-decay]
Memories fade over time unless reinforced by use.
### How It Works [#how-it-works]
**Recency**: A memory accessed yesterday scores much higher than one from three months ago. The 30-day half-life means scores roughly halve each month without access.
**Frequency**: Your 10th access to a memory matters more than your 100th. This mirrors how human memory works: early repetitions build durability, later ones have diminishing returns.
**Importance Floor**: Memories marked as high importance never fully decay. Even untouched, they maintain minimum accessibility. This protects foundational knowledge from fading away.
### Search Reinforcement [#search-reinforcement]
Starting from v0.6.6, every search appearance updates a memory's last-accessed time and access count, strengthening its freshness score automatically.
Previously, only explicit clicks updated freshness. Now, appearing in search results counts as a light access, keeping actively relevant memories from fading.
### Confidence [#confidence]
Confidence scoring is computed during the daily freshness refresh.
Separate from decay, each memory builds a **confidence score** that reflects how well-validated it is. Confidence starts at a baseline and grows as evidence accumulates:
* **Search usage**: Appearances, clicks, and reading time
* **Knowledge graph**: Memories confirmed or enriched by other memories, or used as sources for crystallized knowledge
Unlike decay which fades with time, confidence only increases. A memory that has been frequently accessed, clicked, and connected to other knowledge scores higher than a freshly created one with the same semantic match.
The influence is subtle (confidence contributes about 5% of the final score), but it gives well-established knowledge a consistent edge.
### What This Means [#what-this-means]
* Active knowledge stays fresh, including memories that appear in search results
* Old memories don't disappear, they just rank lower when equally relevant
* Important knowledge persists regardless of access patterns
* Well-validated memories get a subtle ranking boost
* The system learns from your behavior automatically
### Automatic Maintenance [#automatic-maintenance]
These features are opt-in via Settings → Processing → Advanced.
To keep decay scores accurate and memory quality high, Nowledge Mem can run background maintenance:
* **Freshness refresh**: A daily task recomputes decay and confidence scores across all memories, so ranking stays current even for memories you haven't touched recently. This changes scores only; it does not archive, merge, delete, or rewrite memories.
* **Memory Maintenance**: A review-first task looks for memory growth pressure. It can prepare a Timeline review for stale low-risk facts/events that could move out of everyday recall, and for protected knowledge that may need semantic organization.
* **Compaction**: A weekly task identifies clusters of similar or redundant memories and can create links, summaries, or review items. It never silently deletes your saved memory text.
## Temporal Understanding [#temporal-understanding]
Nowledge Mem understands two kinds of time.
### Event Time vs Record Time [#event-time-vs-record-time]
**Event time** is when something actually happened:
* "The 2020 product launch"
* "Last quarter's decisions"
* "Before we migrated"
**Record time** is when you saved the memory. You might record a memory today about an event from 2020.
This matters for queries like "recent memories about 2020 events": things you saved recently (record time) about events from 2020 (event time).
### Temporal Intent Detection [#temporal-intent-detection]
Temporal intent detection requires deep mode search. In fast mode, temporal references are matched by keywords only.
In deep mode, the system interprets temporal references:
| Query | Understanding |
| ---------------------------- | --------------------------- |
| "Decisions from 2023" | Event time: 2023 |
| "Recent memories" | Record time: recent |
| "Recent memories about 2020" | Event: 2020, Record: recent |
| "Before the migration" | Event: before that event |
Fuzzy references like "last quarter," "around 2020," or "early this year" are translated into meaningful filters.
### Date Precision [#date-precision]
When you save a memory about "early 2020," the system:
1. Normalizes to a searchable date (2020-01-01)
2. Tracks precision level (year, month, or day)
3. Preserves original meaning for accurate matching
This lets "memories from 2020" (year precision) work differently from "memories from January 2020" (month precision).
## Feedback Loop [#feedback-loop]
Your usage patterns continuously improve search relevance.
### What We Track [#what-we-track]
| Signal | What It Captures |
| --------------- | -------------------------------------- |
| **Appearances** | How often a memory shows in results |
| **Clicks** | When you open a memory to view details |
| **Dwell time** | How long you spend reading |
### How It Improves Search [#how-it-improves-search]
* High click-through rate indicates the memory is genuinely useful
* Long dwell time suggests valuable content
* Frequent appearances without clicks may indicate declining relevance
No action required. Relevance improves with normal use.
### Automatic Labeling [#automatic-labeling]
Labels are assigned automatically when new memories are created.
When you create a memory, Background Intelligence reads its content and assigns 2–4 descriptive labels. It reuses existing labels when they fit, following a consistent lowercase-hyphenated convention (like `machine-learning` or `project-alpha`). This means your memories are organized from the start without manual tagging.
## Graph-Powered Discovery [#graph-powered-discovery]
The knowledge graph enables discovery through entity and topic connections.
### How Memories Connect [#how-memories-connect]
Each memory can link to:
* **Entities**: People, concepts, technologies, places mentioned
* **Other memories**: Through shared entities or relationships
* **Communities**: Graph Analysis detected topic clusters
### Search Through Connections [#search-through-connections]
**Entity-mediated**: Find memories about "database optimization" even when tagged differently, through shared entities like PostgreSQL or indexing.
**Community-mediated**: A search about "authentication" might surface memories from your "Security Practices" community.
**Graph expansion**: Start from one memory and explore connected knowledge.
## Search Modes [#search-modes]
Two modes, available across all interfaces:
### Fast Mode [#fast-mode]
* Under 100ms typical response
* Direct semantic and keyword matching
* Entity and community search without language model analysis
* Best for quick lookups
### Deep Mode [#deep-mode]
* Full language model analysis
* **Temporal intent detection** (e.g., "recently working on; social events in last decade")
* Query expansion for better recall
* Context-aware strategy weighting
* Better for exploratory searches
Both modes work in main search, global launcher, and API.
## Result Transparency [#result-transparency]
Every result shows why it ranked where it did.
### Search Query Details [#search-query-details]
After each search, you can view detailed analysis of how your query was interpreted:
* Which search strategies were used
* Temporal intent detection results (in deep mode)
* Query expansion and entity extraction
### Score Breakdown [#score-breakdown]
Hover over any result's score to see a breakdown of how it was calculated:
* **Semantic score**: How well the content matches your query
* **Decay score**: Freshness based on recency and frequency
* **Confidence**: How well-validated through usage and graph connections
* **Temporal boost**: Event time relevance (when applicable)
* **Graph signals**: Entity and community connections
This makes it clear how usage patterns influence ranking and why certain memories appear for specific queries.
# Linux Server Deployment (/docs/server-deployment)
Nowledge Mem can run as a **headless server** on Linux machines without a GUI. For a real server setup, use the Linux package and manage it from the command line. You can then open the built-in web app from a browser on the same machine, or connect other clients with an API key.
Background intelligence features such as daily briefings, insight detection, and knowledge graph enrichment require a configured Remote LLM and the appropriate license for your build. The server guide itself is about deployment, not packaging.
Use `sudo` for package installation and system service installation.
Run day-to-day commands like `nmem serve`, `nmem config ...`, `nmem license ...`, and `nmem tui` as your normal Linux user.
Recent builds block these stateful commands when you reach `root` through `sudo` or another elevation step, so a fresh install does not silently create `root`-owned Mem state in the wrong user environment.
If you intentionally log in as `root` on a root-only VPS, Mem will still use `/root` normally.
## System Requirements [#system-requirements]
| Requirement | Specification |
| -------------------- | ------------------------------------------------------------------------------- |
| **Operating System** | Ubuntu 22.04+, Debian 12+, or compatible (via AppImage) |
| **Architecture** | `x86_64` for `.deb` / AppImage; `x86_64` and `arm64` for Docker |
| **Memory (RAM)** | 8 GiB minimum (16 GiB recommended) |
| **Disk Space** | 10 GiB available |
| **Dependencies** | `libgtk-3-0`, `libwebkit2gtk-4.1-0`, `zstd` (installed automatically by `.deb`) |
## Installation [#installation]
Set up the APT repository for automatic updates via `apt upgrade`:
```bash
curl -fsSL https://nowledge-co.github.io/community/apt/install.sh | sudo bash
sudo apt-get install nowledge-mem
```
This adds the GPG signing key and repository source. To update only Mem later, run `sudo apt-get update && sudo apt-get install --only-upgrade nowledge-mem`. Normal system-wide upgrades still work through `sudo apt-get update && sudo apt-get upgrade`, or via `unattended-upgrades` if configured.
For a headless server on a VPS, NAS, cloud VM, or homelab box, the Docker path is a separate guide:
```bash
git clone https://github.com/nowledge-co/community.git
cd community/docker
./nmemctl up
```
See **[Docker Deployment](/docs/docker)** for the full walkthrough: multi-arch (`amd64` + `arm64`), the "For your agent" skill, bind-mount layout, image verification, Caddy TLS, backup/migration, and the optional web-UI auto-update.
```bash
BROWSER_UA='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
# Download the package
curl -A "$BROWSER_UA" -L -o nowledge-mem.deb https://nowled.ge/download-mem-deb
# Install the package
sudo dpkg -i nowledge-mem.deb
# Fix any missing dependencies
sudo apt-get install -f -y
```
```bash
BROWSER_UA='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
# Download the AppImage
curl -A "$BROWSER_UA" -L -o nowledge-mem.AppImage https://nowled.ge/download-mem-appimage
# Portable use only
chmod +x nowledge-mem.AppImage
./nowledge-mem.AppImage
```
For a headless-first Linux server, prefer the APT, Docker, or `.deb` install path.
AppImage is best for portable/manual use, not unattended server setup.
It does not install the `nmem` CLI into your PATH, so it is not the cleanest `nmem` + systemd workflow on a machine with no desktop session.
If you download packages from a terminal, use the commands above as written.
They include a browser User-Agent because some download endpoints return `403` to plain `curl` / `wget` requests.
APT and `.deb` installs automatically:
* Extracts the bundled Python runtime
* Creates the `nmem` CLI at `/usr/local/bin/nmem`
* Configures the APT repository for automatic updates (if installed via APT)
* Sets up the desktop entry (ignored on headless servers)
Verify the CLI is available:
```bash
nmem --version
```
If you used the AppImage instead, run the AppImage file directly each time. It does not add `nmem` to your PATH.
## Docker (preview) [#docker-preview]
This page covers the `.deb` / APT / systemd path on Linux servers. Docker is a separate deployment model with its own walkthrough. It uses the same Mem backend, same web app, and same data, but the lifecycle (compose, bind mounts, image upgrades, optional web-UI auto-update) is different enough to live on its own page.
See **[Docker Deployment](/docs/docker)** for the full guide: when Docker is the right choice (VPS, NAS, cloud VM, homelab), supported architectures (`amd64` + `arm64`), quick start with `nmemctl`, the "For your agent" skill, where your data lives, memory tuning, image verification, Caddy TLS, backups and migration, and the optional web-UI auto-update.
## Quick Start [#quick-start]
For a real Linux server, set up the background service first. That gives you one stable local Mem server so the next commands work cleanly from SSH, across new terminals, and after reboot.
### Install the background service [#install-the-background-service-step]
Recommended on servers:
```bash
sudo nmem service install --service-user
```
If you truly want a user-level service instead:
```bash
nmem service install --user
```
On headless servers, prefer the system service.
A user service only survives logout and reboot if lingering is enabled for that account:
```bash
sudo loginctl enable-linger
```
### Verify the service [#verify-the-service-step]
```bash
nmem service status
nmem status
```
To confirm exactly which build is running, print the build SHA:
```bash
nmem-server --build-info
```
The same value appears in `GET /health` under `.build_sha`, so you can verify a deployment over the network or from a script.
### Activate Your License [#activate-your-license-step]
```bash
nmem license activate # Email is usually inferred from the key
nmem license status # Verify activation
nmem license renew # Refresh this device later if authorization expires
```
If email inference fails, run `nmem license activate ` explicitly.
### Open the Web App [#open-the-web-app-step]
Print the browser login details:
```bash
nmem key --show-login
```
If your current build does not support `--show-login` yet, use:
```bash
nmem key
```
Then open the URL it prints. On the default setup, that is usually:
```text
http://127.0.0.1:14242/app
```
On a headless server, your browser is usually on another computer. Use the exact
URL and port that `nmem key --show-login` prints.
If you need an SSH tunnel, forward that same port:
```bash
ssh -L :127.0.0.1:
```
Then open the matching local URL in your browser and paste the API key.
### Download the Search Index Model [#download-the-search-index-model-step]
```bash
nmem models download
nmem models status # Verify installation
```
This downloads the Search Index Model for hybrid search (\~500 MB). Only needed once.
When you run headless, use these two commands as your quick search-health check:
* `nmem status`: shows whether search is ready, rebuilding is needed, or Mem is only filling metadata in the background
* `nmem models status`: shows the model state plus the current search-index action, if any
`GET /health` carries the same signal for scripts and remote checks. Two fields matter:
* `embedding.mode` is `remote`, `local-gguf`, or `local-hash-fallback`. The hash-fallback value means no real embedder is configured, so semantic search is degraded while keyword search still works. That is the signal to set a remote provider or download the local model.
* `reindex_needed` is `true` when the search index is stale, usually after the embedding identity changes (a new provider or model).
The server never blocks boot to rebuild. It starts immediately and serves keyword (FTS) search while the index catches up, so a stale index fails soft to keyword results rather than erroring. Trigger the rebuild when you are ready, from **Settings → Memory Processing → Search** or with `POST /search-index/reindex`. If you would rather rebuild eagerly on boot, set `NMEM_BOOT_AUTO_REINDEX=1` before starting the server.
### Configure the LLM Provider [#configure-the-llm-provider-step]
A remote LLM is required on Linux (no on-device LLM support):
```bash
nmem config provider set anthropic \
--api-key sk-ant-xxx \
--model claude-sonnet-4-20250514
nmem config provider test # Verify connection
```
Supported providers include `anthropic`, `openai`, `gemini`, `xai`, `deepseek`, `minimax`, `zai`, `moonshot`, `ollama`, `openrouter`, and OpenAI-compatible endpoints.\
See the full provider matrix and caveats: [LLM Providers](/docs/llm-providers).
### Enable Background Intelligence [#enable-background-intelligence-step]
```bash
nmem config settings set backgroundIntelligence true
nmem config settings set autoDailyBriefing true
```
### Verify Everything [#verify-everything-step]
```bash
nmem status
```
### Quick foreground test instead of systemd [#quick-foreground-test-instead-of-systemd-step]
If you do not want to install a systemd service yet:
```bash
nmem serve
```
Keep that terminal open. Then use a second terminal for `nmem license ...`, `nmem models ...`, and `nmem config ...`.
## Running as a systemd Service [#running-as-a-systemd-service]
For production deployments, use `nmem service install` to set up a background systemd service that automatically starts on boot:
```bash
# Install, enable, and start as your normal Linux user
sudo nmem service install --service-user
# If you are running sudo directly from that Linux user, Mem can usually infer it
sudo nmem service install
# Custom host/port
sudo nmem service install --service-user --host 0.0.0.0 --port 8080
```
```bash
# No root required
nmem service install --user
```
For a system service, Mem should run as your normal Linux user, not as `root`.
If `sudo` cannot infer the right account, pass `--service-user `.
For a user service, run `nmem service install --user` directly as that user without `sudo`.
If you want a user service to survive logout and reboot, also run `sudo loginctl enable-linger ` once.
If your VPS is intentionally root-only and you log in as `root` directly, `nmem service install` can still use `/root` consistently.
If you previously ran older builds as `root`, some files under `~/.config/co.nowledge.mem.desktop/` may still be owned by `root`.
In that case, license actions, provider changes, or Access Anywhere settings can fail until you fix ownership for the Linux user that runs the service.
Recent builds now show the exact path when this happens.
A typical repair looks like:
```bash
sudo chown -R : ~/.config/co.nowledge.mem.desktop
sudo chown -R : ~/.local/share/NowledgeGraph
```
If you use custom `XDG_CONFIG_HOME` or `XDG_DATA_HOME`, repair those locations instead.
### Managing the Service [#managing-the-service]
```bash
nmem service status # Show service status
nmem service logs -f # Follow service logs
nmem service stop # Stop the service
nmem service start # Start the service
nmem service uninstall # Stop, disable, and remove
```
Add `--user` to any `nmem service` command if you installed a user-level service.
### serve vs service [#serve-vs-service]
| | `nmem serve` | `nmem service install` |
| ------------------ | ----------------------------- | -------------------------------------- |
| **Runs in** | Foreground (current terminal) | Background (systemd) |
| **Stops when** | Ctrl+C or terminal closes | `nmem service stop` or system shutdown |
| **Starts on boot** | No | Yes (auto-enabled) |
| **Best for** | Testing, development | Production deployments |
## Data Location [#data-location]
All data (graph database, search index, version metadata) is stored in a single directory:
```
~/.local/share/NowledgeGraph/
├── nowledge_graph_v2.db/ # KuzuDB graph database
├── search_index/ # LanceDB vector + BM25 index
└── db_version.json # Schema version tracking
```
The server resolves this path automatically using `XDG_DATA_HOME` (defaults to `~/.local/share`). To use a custom location, set the `NOWLEDGE_DB_PATH` environment variable **before** starting the server:
```bash
export NOWLEDGE_DB_PATH=/mnt/data/NowledgeGraph/nowledge_graph_v2.db
nmem serve
```
Older versions stored data in `./data/` relative to the working directory. After upgrading, the server will
auto-detect legacy data and print migration instructions. If your data seems missing, see
[Troubleshooting: Missing data after upgrade](#missing-data-after-upgrade) below.
## Remote Access [#remote-access]
By default, `nmem serve` listens on `127.0.0.1` only. That is enough for:
* `nmem` commands on the server itself
* the built-in web app on the same local URL (by default `http://127.0.0.1:14242/app`)
If you bind to `0.0.0.0` or another non-loopback address, Mem requires an API key for other machines. The key is auto-generated when needed, and you can print it again at any time with:
```bash
nmem key
# or
nmem key --show-login
```
Once the server is reachable, connect clients through the highest-level surface they support: native connectors first, then plugin settings or `nmem` config, and only then direct MCP when no better dedicated path exists. The main exception today is Codex, where the dedicated package already bundles local MCP and remote deployments should override that endpoint in Codex config.
```bash
# On the server
nmem serve
nmem key
```
Install the standalone CLI on remote machines:
```bash
pip install nmem-cli
# or
uv pip install nmem-cli
```
Then configure the connection. The recommended persistent setup is:
```bash
nmem config client set url http://your-server:14242
nmem config client set api-key nmem_...
```
That writes `~/.nowledge-mem/config.json` for this machine. If you only need a temporary shell session, use environment variables instead:
```bash title="Temporary shell override"
export NMEM_API_URL=http://your-server:14242
export NMEM_API_KEY="nmem_..."
```
```bash
nmem status
nmem m search "query"
```
Priority: CLI flags > env vars > config file > defaults.
Commands like `nmem t save --from claude-code`, `grok`, `gemini-cli`, or `codex` still read local agent session files on the client machine running that agent. Pointing `nmem` at a remote server changes where the normalized data is uploaded, not where session discovery happens.
To disable authentication (not recommended for production):
```bash
nmem serve --no-auth
```
API key authentication is enabled by default for connections from other machines. Localhost browser access can also require a key if you enable localhost auth. For additional security, restrict access via firewall rules or use [Access Mem Anywhere](/docs/remote-access) with a Cloudflare tunnel.
## Interactive TUI [#interactive-tui]
For an interactive terminal experience, use the TUI:
```bash
nmem tui
```
The TUI provides a full settings management interface including license activation, LLM configuration, and knowledge processing toggles.
It is bundled in the Docker image too. On a container deployment, run it inside the container:
```bash
docker compose exec -it mem nmem tui
```
It also includes **Access Anywhere** controls in `Settings`, and the same screen can reveal the current API key plus the local web login URL. That makes it practical to complete the `/app` login flow even on a headless server.\
Full guide: [Access Mem Anywhere](/docs/remote-access).
If your server network blocks UDP/QUIC and Access Anywhere fails to come online, force Cloudflare transport to HTTP/2 before restarting Mem:
```bash
export TUNNEL_TRANSPORT_PROTOCOL=http2
```
## Configuration Reference [#configuration-reference]
### Environment Variables [#environment-variables]
| Variable | Default | Description |
| ----------------------- | ------------------------ | -------------------------------------------------------------- |
| `NMEM_API_URL` | `http://127.0.0.1:14242` | Server URL for CLI commands |
| `NMEM_API_KEY` | `-` | API key for authenticated requests |
| `NOWLEDGE_DB_PATH` | Auto-detected | Override database location |
| `NOWLEDGE_BACKEND_HOST` | `127.0.0.1` | Server bind address |
| `NMEM_LAN_AUTH` | `-` | Set to `disabled` to skip authentication (same as `--no-auth`) |
### CLI Commands Summary [#cli-commands-summary]
| Command | Description |
| -------------------------------------------- | ----------------------------------------------------- |
| `nmem serve` | Start the server (default: same machine only) |
| `nmem serve --no-auth` | Start without API key authentication |
| `nmem service install` | Install and start as a systemd service |
| `nmem service status` | Show systemd service status |
| `nmem service logs -f` | Follow service logs |
| `nmem service stop` / `start` | Stop or start the service |
| `nmem service uninstall` | Remove the systemd service |
| `nmem status` | Check server health |
| `nmem license activate [email]` | Activate license (email is usually inferred) |
| `nmem license renew` | Refresh or renew this device authorization |
| `nmem models download` | Download Search Index Model |
| `nmem config provider set
--api-key ` | Configure LLM provider |
| `nmem config provider test` | Test LLM connection |
| `nmem config settings` | Show processing settings |
| `nmem config settings set ` | Update a setting |
| `nmem update` | Check for available updates |
| `nmem update apply` | Download and apply update |
| `nmem tui` | Interactive terminal UI |
| `nmem key` | Print the current API key |
| `nmem key --show-login` | Print the local web app URL together with the API key |
## Troubleshooting [#troubleshooting]
### Missing data after upgrade [#missing-data-after-upgrade]
Older versions (before 0.7) stored the database in `./data/` relative to the directory you ran `nmem serve` from. The current version stores data in the standard location (`~/.local/share/NowledgeGraph/`). If your memories disappeared after upgrading, your data is likely still on disk, just in the old location.
#### Find your old data [#find-your-old-data-step]
Search common locations where the old database may be:
```bash
find / -name "nowledge_graph*.db" -type d 2>/dev/null
```
Typical locations include:
* `~/data/nowledge_graph.db`, if you ran `nmem serve` from your home directory
* `/data/nowledge_graph.db`, if the systemd service ran from `/` (system service without `WorkingDirectory`)
* `/path/where/you/ran/nmem/data/nowledge_graph.db`, any other working directory
#### Move to the standard location [#move-to-the-standard-location-step]
```bash
# Stop the server first
nmem service stop # if using systemd
# or Ctrl+C # if running in foreground
# Create the standard directory if needed
mkdir -p ~/.local/share/NowledgeGraph
# Move your database and related files
mv /old/path/data/nowledge_graph*.db* ~/.local/share/NowledgeGraph/
mv /old/path/data/search_index ~/.local/share/NowledgeGraph/ 2>/dev/null
mv /old/path/data/db_version.json ~/.local/share/NowledgeGraph/ 2>/dev/null
# Restart the server
nmem serve # or: nmem service start
```
#### Verify recovery [#verify-recovery-step]
```bash
nmem m search "test" # Search for your memories
nmem status # Check server health
```
Starting with the current version, `nmem serve` prints the database path at startup. This makes it easy to verify which location is being used. If legacy data is detected in `./data/`, the server prints migration instructions automatically.
## Next Steps [#next-steps]
* **[CLI Reference](/docs/cli)**: Complete CLI documentation
* **[API Reference](/docs/api)**: REST API endpoints
* **[Connectors](/docs/integrations)**: Connect with AI tools
# Spaces (/docs/spaces)
Spaces are an optional way to keep different kinds of knowledge focused without splitting Mem into separate apps.
Most people do not need them on day one. Staying in **Default** is the right choice until two contexts keep getting in each other's way.
If you are not already feeling real overlap between projects, teams, or agents, leave spaces off and keep using the default space.
## The First Useful Move [#the-first-useful-move]
Create one extra space only when you already know why you need it.
Good first cases:
* a long-running work project that should not mix with personal notes
* an agent that should build up its own experience over time
* a shared team space that several tools should search first
Go to **Context → Spaces**, turn spaces on, and create one space with a clear name.
Save one memory in the new space, switch back to **Default**, and confirm it no longer appears in the default Memories view. Then switch back and find it immediately.
## What Spaces Change [#what-spaces-change]
When a space is active, these views follow it by default:
* **Memories**
* **Threads**
* **Library**
* **Working Memory**
* **AI Now**
The **Timeline** also starts from the active space, while still letting you expand back to all activity when you want the wider picture.
The **entity graph stays global by design**. Mem still understands the whole shape of your knowledge. Spaces change what your day-to-day memory surfaces read and write by default.
## What The Settings Actually Mean [#what-the-settings-actually-mean]
Inside a space profile you will see three settings that matter most:
* **Automatic recall in this space**
* **Stay in this space** keeps the first recall step inside the current lane.
* **Stay here + shared spaces** starts here, then also reads the spaces you marked as shared context.
* **Search every space** is for the rare lane that should search across your whole memory by default.
* **Shared context for recall**
* This is retrieval only.
* It does **not** move memories into those spaces.
* It does **not** merge spaces together.
* **How agents should work here**
* AI Now, Feed, and built-in background agents read this when they work in that space.
* It changes how they search and explain.
* It does **not** change where records are stored.
## Working Memory In Spaces [#working-memory-in-spaces]
Working Memory is no longer just one global file.
* The **Default** space keeps the familiar compatibility path at `~/ai-now/memory.md`.
* Other spaces get their own Working Memory briefing behind the same Mem interfaces.
* Connected tools read the briefing for the current space when they know which space they are in.
That means a research agent can open with its own current priorities, while your default personal space stays quieter.
If a space no longer has memories, threads, or Library items, but still has its own Working Memory notes, Mem will tell you that clearly when you delete the space and let you remove those generated notes in the same step.
## Moving Existing Records [#moving-existing-records]
If you created a space after using Mem for a while, you do not have to recreate your history.
In **Memories** or **Threads**, turn on selection mode, choose the items you want, then use **Move** to send them to another space. For a larger cleanup, select the current page first, then choose **All pages** to move or delete every primary item in the current space.
Shared context does not move records. It only lets one space read another space when recall is configured that way.
## How AI Tools Use Spaces [#how-ai-tools-use-spaces]
The best integrations treat space as background context, not as a new thing you have to explain every turn.
* **AI Now** follows the current space in the app.
* **Native integrations** should store the lane in their own profile or provider config when the host already knows it.
* **CLI workflows** can opt into a space with `--space ""`.
* The HTTP and MCP APIs still use the `space_id` field name for compatibility, but they accept the visible space name too.
You can preview the result in **Context** before starting a new tool session.
```bash
nmem --json wm read --space "Research Agent"
nmem --json m search "token rotation" --space "Research Agent"
nmem spaces
```
If a tool has no natural project or agent context, it should simply stay in **Default**.
If an integration already has a real settings surface, use that to choose the lane. Environment variables are only the fallback for CLI-first tools that have no better profile-level config.
## Multi-Agent Hosts [#multi-agent-hosts]
Not every integration can route spaces at the same level.
* **Coding tools** like Claude Code, Grok Build, Codex, and Gemini CLI usually only need one optional lane for the whole session.
* **Agent harnesses** like Hermes, Alma, Bub, and OpenClaw may need one lane per profile, process, or agent identity.
The right pattern is:
* **Fixed lane**: one profile or process always stays in one space
* **Derived lane**: the host already knows a stable identity or workspace and derives the space from it
* **Exact mapping**: the host exposes a small known set of identities and maps each one to a named space
If a host does not expose a trustworthy identity or workspace signal, do not invent per-agent routing anyway. Use one fixed lane per profile or process, or stay on Default.
## When Spaces Help Most [#when-spaces-help-most]
Spaces are strongest when you want focus, not isolation for its own sake.
They work especially well for:
* one owner with several long-running agents
* separating work from personal context
* a shared project space plus a quieter default space
* teams that want one common context without mixing every private note into it
## What Not To Worry About Yet [#what-not-to-worry-about-yet]
* You do not need a work space and a life space just because the feature exists.
* You do not need to redesign your labels or graph usage to start using spaces.
* You do not need to split the entity graph. Mem keeps that global on purpose.
## Next Steps [#next-steps]
* [Memories](/docs/memories) if you want the capture and search workflow
* [Context](/docs/ai-context) if you want to see what a connected AI receives
* [AI Now](/docs/ai-now) if you want a space-aware agent workspace
* [Nowledge Mem CLI](/docs/cli) if you want to script `--space` and `nmem spaces`
* [Background Intelligence](/docs/advanced-features) if you want to understand how Working Memory and scheduled tasks behave over time
# Start Here (/docs/start-here)
Nowledge Mem is easiest to understand through one loop:
* save something that matters
* find it again
* let one real tool use it
This page is the shortest path to that loop. If you have not installed yet, go to [Installation](/docs/installation) first; everything below assumes the app is running.
## What Mem Is [#what-mem-is]
At its simplest, Mem does three things:
* it stores your decisions, insights, files, and conversations
* it makes them searchable and reusable later
* it lets the tools you connect work from the same memory instead of starting cold
If you plan to use Mem across several devices, the model is straightforward: run one Mem on an always-on machine and let your other clients connect to it. See [Sync Across Devices](/docs/sync).
You do not need to understand the whole product before it becomes useful.
## The First Loop [#the-first-loop]
### Save One Real Memory [#save-one-real-memory-step]
In the Timeline, write one real thing you want to keep: a decision you made, an insight from work, a preference you repeat often. Press Enter.
### Confirm Search Can Find It [#confirm-search-can-find-it-step]
Ask the Timeline a direct question such as:
> What did I decide about authentication?
If the answer reflects what you just saved, you already have a working loop.
### Connect One Real Tool [#connect-one-real-tool-step]
Instead of choosing a tool from a long list first, start with one instruction. Your agent uses the best supported setup path for the host it is running in.
## Connect Any AI Tool [#connect-any-ai-tool]
Open the AI tool you actually use (Claude Code, Grok Build, Codex, Cursor, Gemini CLI, Copilot CLI, OpenClaw, Hermes, Droid, Alma, Bub, Pi, OpenCode, OMP, Paseo, or Claude Desktop) and paste this prompt:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for the AI tool I am using.
```
That URL is a machine-readable install contract. The agent fetches it, detects which host it is running in, uses the right install or setup path, verifies the connection with `nmem status`, and asks you to restart the host when needed. Command-line hosts can usually be installed directly. App-based hosts may still ask you to confirm a marketplace step.
The agent usually knows which host it lives in. It can read [SKILL.md](https://mem.nowledge.co/SKILL.md), run the matching plugin install or MCP config command when the host allows it, and tell you what changed. You confirm any manual app step and restart; the loop becomes visible.
### Remote or cross-device setup [#remote-or-cross-device-setup]
If Mem runs on the same machine as the AI tool, the generic prompt above is enough. The agent will configure the local endpoint at `127.0.0.1:14242` and stop there.
If the AI tool runs on another machine, or if you are using a managed or self-hosted remote Mem server, first point this machine's CLI at that server:
```bash
nmem config client set --url https://your-mem-server.example --api-key nmem_...
```
In the desktop app, find remote URL and key controls under **Settings → Access Anywhere**. Use that path when:
* you are on **Pro** and want the agent to use your managed Nowledge Link endpoint
* you are on **Lifetime** with a self-hosted Mem and need cross-device access
* you want the agent to talk to your Mem from a machine other than the one running it
## Definition of Done [#definition-of-done]
You should be able to answer yes to all of these:
* I saved one memory in the Timeline
* I searched for it and got it back
* I pasted the Connect prompt into my AI tool, it completed the install or told me the exact manual step, and I restarted that tool
* In a fresh session of that tool, the agent could read my Working Memory (empty is fine on day one)
If any answer is no, see [How To Know Mem Is Working](/docs/verify-it-works) for verification steps.
## When The Connect Prompt Does Not Fit [#when-the-connect-prompt-does-not-fit]
A small set of surfaces install differently, because they are not driven by a chat-style agent:
* **Browser Extension** for web chat (ChatGPT, Claude.ai, Gemini, Poe): install from the Chrome Web Store, open the side panel, connect it to Mem. Guide: [Browser Extension](/docs/integrations/browser-extension).
* **Raycast**: install from the Raycast Store. Guide: [Raycast](/docs/integrations/raycast).
* **Trajectory extractors** for Windsurf, Antigravity: external CLIs that export sessions to disk for one-time import. Guide: [Import existing conversations](/docs/import-existing-conversations).
For everything else, use the Connect prompt. If your host is not yet in `SKILL.md`'s table, ask the agent to read the file anyway and report what it tried; we add hosts as they appear in the wild.
## Bring In Conversations You Already Have [#bring-in-conversations-you-already-have]
If you are migrating from ZIP/JSON/HTML exports (ChatGPT, DeepSeek, ChatWise, Alma), local coding-agent sessions, or single `.md` threads, start from [Import existing conversations](/docs/import-existing-conversations). It maps each case to the exact Mem screen so you do not bounce between Threads and Connectors.
Save one memory. Run the Connect prompt for one tool. Restart that tool. Stop. The point on day one is to prove the loop, not to wire every surface at once.
## Next Steps [#next-steps]
* [Installation](/docs/installation): install and finish first boot
* [Getting Started](/docs/getting-started): the Timeline and your first captures
* [Connectors](/docs/integrations): connector reference (behavior, skills, distillation)
* [How To Know Mem Is Working](/docs/verify-it-works): verify the full loop
* [Access Anywhere](/docs/remote-access): run Mem on one machine and reach it from everywhere
* [Sync Across Devices](/docs/sync): the single-Mem, multi-client sync model
# Sync Across Devices (/docs/sync)
Yes. Nowledge Mem supports sync today.
But it works in a specific way:
* one Nowledge Mem instance is the single source of truth
* other clients connect to that same instance
* your memories, threads, graph, and library stay consistent because everyone is using the same backend
This is different from running several separate Mem databases and merging them later.
If you want a backup or one-time migration instead of ongoing multi-device access, use [Back Up, Export, and Import](/docs/data-portability).
## What Sync Means In Mem [#what-sync-means-in-mem]
The recommended setup is simple:
1. Run Nowledge Mem on an always-on machine.
2. Turn on [Access Anywhere](/docs/remote-access).
3. Connect your other clients to that same Mem.
That can be:
* the desktop app on another computer
* the web app at `/app`
* the mobile app
* the browser extension
* `nmem` CLI
* supported agent integrations running on other machines
If they all point to the same Mem URL and API key, they are working against the same knowledge base.
## What This Is Not [#what-this-is-not]
Mem does **not** currently mean:
* several independent local Mem apps automatically replicating and reconciling with each other
* a centralized Nowledge-hosted account backend
* offline-first multi-master sync between separate databases
Today, sync means one Mem hub and many clients.
## When This Is The Right Setup [#when-this-is-the-right-setup]
This model is ideal if you already have:
* a Mac Mini that stays on
* a Linux server
* a desktop machine that acts as your main knowledge hub
* a dedicated agent machine such as an OpenClaw or coding-agent box
You keep one long-running Mem there, then access the same knowledge base from everywhere else.
Historically, people mostly saw remote access through the browser extension and `nmem` CLI, so many assumed Mem did not really support sync. That is out of date. Web access, desktop client mode, and the mobile app now make the single-Mem multi-client model much more visible.
## What To Read Next [#what-to-read-next]
* Read [Access Anywhere](/docs/remote-access) for setup, security, Cloudflare tunnel steps, and client-specific connection instructions.
* Read [Back Up, Export, and Import](/docs/data-portability) if you want a portable backup or one-time migration.
* Read [AI Now](/docs/ai-now) if you want to use the desktop client remotely with the same knowledge base.
* Read [Verify It Works](/docs/verify-it-works) if you want to confirm that another device is really connected to the same Mem.
# Threads (/docs/threads)
Threads are your conversation layer. They keep the original flow of what happened in an AI session: what you asked, what the tool answered, and how the work evolved.
Their real value is not just storage. Threads become useful when you can search past conversations, reopen exact context, and distill the durable parts into [memories](/docs/memories).
If you need the original messages, save or import a thread. If you only need the durable takeaway, distill it into memories and work from there.
If you are deciding **how** to bring existing conversations in (bulk file vs coding-agent scan vs browser vs one markdown file), read **[Import existing conversations](/docs/import-existing-conversations)** first. This page remains the **format and feature reference** for Threads.
## The First Useful Thread [#the-first-useful-thread]
If you are new, do one of these first:
* import one conversation you already care about
* let one supported tool capture a full session
* capture one web conversation through the browser extension
Then open that thread and distill one useful memory from it. That is the core workflow.
| I want to... | Jump to |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| See **every import path** in one overview | [Import existing conversations](/docs/import-existing-conversations) |
| Browse and search threads | [Browsing Threads](#browsing-threads) |
| Distill threads into memories | [Thread Distillation](#thread-distillation) |
| Auto-import from **coding agents** | [Auto-Sync](#auto-sync) |
| Capture from **web AI chats** | [Browser Extension](#browser-extension) |
| Import my **ChatGPT**, **DeepSeek**, or **Raycast AI** (exporter JSON) conversations | [Bulk Import](#bulk-import) |
| Import a **conversation file** (`.md` with `## User`/`## Assistant` headers) | [Single Thread](#single-thread) |
| Learn the **.md** conversation format | [Conversation Markdown](#conversation-markdown-format) |
| Import via **API** | [Import API](#import-api) |
| Import via **CLI** | [CLI](#cli) |
## Browsing Threads [#browsing-threads]
The Threads view shows all your imported conversations in one place.
* **Search** threads by content or title
* **Filter** by source (Claude Code, ChatGPT, Cursor, etc.)
* **Pin** important threads to keep them accessible
* **View** individual messages within any thread
Open Threads from the sidebar or press Cmd + 3 (macOS).
## Thread Distillation [#thread-distillation]
The key workflow that connects threads to memories. Open any thread and trigger distillation. The system extracts individual memories from the conversation, each with its own title, labels, and importance score. The extracted memories enter your knowledge graph and become searchable alongside everything else.
This is how hours of AI conversation become connected knowledge you can find later.
For normal-sized threads, distillation runs right away. For very large threads, Mem now offers **Smart Background Distillation** instead: it starts a few seconds later, lets the Knowledge Agent read the thread progressively, and then saves a smaller set of durable memories. This is slower than a short-thread distill, but much safer than forcing one foreground request to read everything at once.
The [browser extension](/docs/integrations/browser-extension) supports Smart Distill directly from web conversations, so you can capture memories without importing the full thread first.
## How Threads Reach Mem [#how-threads-reach-mem]
Threads can enter Nowledge Mem through several different paths. They are related, but they are not the same:
* **Dedicated plugins and extensions**: tool-specific integrations like Claude Code, Grok Build, Codex, Gemini CLI, OpenClaw, Hermes Agent, Alma, Cursor, Droid, OpenCode, Craft Agent, and Copilot CLI
* **Local discovery/backfill**: in-app import for supported coding-agent conversations on the machine running Mem
* **Shared skills or prompt packs**: reusable setups like `npx skills`
* **Browser capture**: the Exchange extension works with the **focused web session** you use in the panel (not your full chat account); see [Import existing conversations](/docs/import-existing-conversations)
* **Manual import**: files, exports, API calls, and CLI imports
The main thing to understand is this:
* **Full session capture** means Mem receives the actual recorded conversation from that tool
* **Handoff summary** means Mem stores a concise continuation note instead of the full session
Shared skills matter here too. They are useful across many agents, but they cannot honestly promise full session capture unless that host runtime exposes readable session files or a stable transcript API.
Most users only need one rule:
* if your tool already has a real thread-save path, use it
* if it only supports handoff summaries today, keep that mental model clear and use import or `nmem t sync` for full history
## Auto-Sync [#auto-sync]
### In-App Discovery [#in-app-discovery]
Scan your machine for conversations from local coding assistants. No file export needed.
This path scans conversation files on the machine running Nowledge Mem. It is excellent for local sync, but it is different from `nmem t sync --from ...`, which reads local session files client-side and can still upload normalized threads to a remote Mem server.
Importing saves that conversation as a thread right away. If Auto-Sync is on, Mem can then append new messages to that thread, and it can remember the detected project for later sessions when that app exposes a stable project path.
| Client | Sync Mode | Where |
| --------------- | ------------------------------------------------------------------ | ---------------------------------------- |
| **Claude Code** | Auto-discovery + incremental sync | Threads → Import → Find AI Conversations |
| **Cursor** | Auto-discovery + incremental sync | Threads → Import → Find AI Conversations |
| **Codex** | Auto-discovery + incremental sync | Threads → Import → Find AI Conversations |
| **OpenCode** | Backfill older sessions; new work is captured by the native plugin | Threads → Import → Find AI Conversations |
### Native Capture And Save Paths [#native-capture-and-save-paths]
Different integrations expose different thread-save behavior. Some support full session capture. Some auto-capture on lifecycle events. Droid and Cursor currently keep plugin handoff summaries separate from full conversation import.
| Integration | What it saves | How it works | Setup |
| ------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Claude Code** | Full session capture | Stop hook auto-saves the session after each response. Also supports explicit `/save`. `nmem` reads local session files client-side before upload. | [Claude Code guide](/docs/integrations/claude-code) |
| **Grok Build** | Full session capture | Grok Build loads the shared Claude-compatible connector, but hooks route saves through `nmem t save --from grok` so the source and session format stay correct. | [Grok Build guide](/docs/integrations/grok) |
| **Gemini CLI** | Full session capture plus separate handoff summary | `save-thread` imports the recorded Gemini session through `nmem t save --from gemini-cli`. The extension also imports before compression and at session end. `save-handoff` stays a separate resumable summary. | [Gemini CLI guide](/docs/integrations/gemini-cli) |
| **Droid** | Handoff summary in the plugin | The Droid plugin intentionally exposes `save-handoff`, not `save-thread`. It provides Working Memory, routed recall, and resumable checkpoints now, while leaving transcript-backed thread save for a future real importer. | [Droid guide](/docs/integrations/droid) |
| **Cursor** | Handoff summary in the plugin | The Cursor plugin intentionally exposes `save-handoff`, not `save-thread`. Use in-app discovery for local Cursor conversation import until a real live session importer exists. | [Cursor guide](/docs/integrations/cursor) |
| **Alma** | Full session capture | Live sync saves conversations after 2 min idle, on thread switch, and on quit (on by default). | [Alma guide](/docs/integrations/alma) |
| **OpenClaw** | Full session capture | Captures every agent session automatically at completion, with optional LLM distillation. | [OpenClaw guide](/docs/integrations/openclaw) |
| **Hermes Agent** | Completed-turn capture with final boundary flush | The native memory provider writes cleaned `user` / `assistant` turns as replies complete, then flushes remaining changes on clean exit, `/new`, and `/reset`. | [Hermes guide](/docs/integrations/hermes) |
| **Codex** | Full session capture | Stop hook captures the recorded Codex session after each turn. Explicit save remains available as a fallback. | [Codex guide](/docs/integrations/codex-cli) |
| **Copilot CLI** | Full session capture | Capture hooks append newly recorded Copilot conversation content into Mem after each response, before compaction, and at session end. Explicit save/checkpoint requests still create a concise summary thread when needed. | [Copilot CLI guide](/docs/integrations/copilot-cli) |
| **Pi** | Full session capture | The native Pi package syncs completed conversations automatically. Older local sessions can be imported with `nmem t sync --from pi`. | [Pi guide](/docs/integrations/pi) |
| **OpenCode** | Full session capture | The native plugin captures when OpenCode reports idle and flushes before compaction. `nowledge_mem_save_thread` remains an explicit fallback; older sessions can be imported with `nmem t sync --from opencode`. | [OpenCode guide](/docs/integrations/opencode) |
| **Craft Agent** | Source-guided memory + import | Craft uses a workspace source and guide for MCP-backed memory behavior. Older local Craft sessions can be imported from `session.jsonl` files with `nmem t sync --from craft-agent`. | [Craft Agent guide](/docs/integrations/craft-agent) |
| **OMP** | Plugin auto-capture plus older-session backfill | The dedicated OMP plugin captures new conversations automatically. Older local OMP sessions can still be backfilled with `nmem t sync --from omp`. Do not use the Pi package as the OMP connector. | [OMP guide](/docs/integrations/omp) |
| **Generic `npx skills` agents** | Handoff summary only | Use `save-handoff`. Shared skills can guide saving, but they do not control the host runtime well enough to promise transcript-backed import everywhere. | [Connectors overview](/docs/integrations) |
If you need exact past conversation history, use a full-session capture or import path. Handoff summaries are for resumable continuity, not full conversation storage.
## File Import [#file-import]
### Bulk Import [#bulk-import]
Import all conversations from an export file at once.
| Source | File Format | How to Export |
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ChatGPT** | `chat.html` | ChatGPT Settings → Data controls → Export data |
| **Claude** | `data-…-batch-….zip` (`conversations.json`, `memories.json`) | claude.ai or Claude Desktop: avatar → **Settings** → **Privacy** → **Export data** ([Anthropic guide](https://support.claude.com/en/articles/9450526-how-can-i-export-my-claude-data)). Not available from Claude mobile apps. |
| **DeepSeek** | `deepseek_conversations.json` | chat.deepseek.com → Settings → Data → Export data |
| **ChatWise** | `.zip` (contains JSON files) | Export all chats from ChatWise app |
| **Alma** | `alma-backup-YYYY-MM-DD.zip` (contains `threads.json`) | Alma Settings → Data → Export all threads |
| **Raycast AI** | `.json` (e.g. `raycast_ai_chats.json`) | No vendor export, so use **[raycast-ai-exporter](https://github.com/daveonkels/raycast-ai-exporter)** on macOS (see that README) |
Bulk Import saves the original conversations as Threads. They are searchable immediately, so you do not need to distill hundreds of imported chats before Mem can find them. Distillation is the second step: use it for conversations that contain decisions, procedures, preferences, or lessons worth keeping as long-term Memories. For a large archive, plan extraction in small batches from the Timeline or by selecting specific threads.
### Single Thread [#single-thread]
Import one conversation from a file.
| Format | File Type | Notes |
| ------------------------- | --------- | --------------------------------------------------------------------------- |
| **Conversation Markdown** | `.md` | `## User` / `## Assistant` / `## System` headers, optional YAML frontmatter |
| **Cursor** | `.md` | Cursor's native export format (auto-detected) |
| **Generic Markdown** | `.md` | Any markdown file, imported as a document |
If your `.md` file is a regular document (no `## User` / `## Assistant` headers), it belongs in the [Library](/docs/library), not Threads. Drag it into the Timeline or import from the Library view.
## Conversation Markdown Format [#conversation-markdown-format]
The portable format for conversation import. Any tool that writes `## User` / `## Assistant` headers produces a file Nowledge Mem can read.
### Minimal Example [#minimal-example]
The simplest valid file, two turns, no frontmatter:
```markdown
## User
What is Python's GIL?
## Assistant
The Global Interpreter Lock (GIL) is a mutex in CPython that allows only one thread to execute Python bytecode at a time. This means CPU-bound multi-threaded programs won't see speedups from threading: use multiprocessing or async I/O instead.
```
### Full Example [#full-example]
With optional YAML frontmatter and a system message:
```markdown
---
title: Python Async Patterns
source: chatgpt
date: 2025-06-15
---
## System
You are a senior Python developer who explains concepts clearly.
## User
How does async/await work in Python?
## Assistant
Python's `async`/`await` lets you write concurrent code that doesn't block while waiting for I/O. An `async def` function returns a coroutine, and `await` pauses it until the result is ready, meanwhile other coroutines can run.
## User
When should I use asyncio vs threading?
## Assistant
Use **asyncio** for I/O-bound work (HTTP requests, database queries, file reads): it's lighter and scales better than threads. Use **threading** when you need to call blocking libraries that don't support async. Use **multiprocessing** for CPU-bound work.
```
### Format Rules [#format-rules]
* **Headers**: `## User`, `## Assistant`, or `## System`, level-2 heading, one per message
* **Content**: Everything between headers is one message. Markdown formatting, code blocks, and lists are preserved as-is
* **Frontmatter**: Optional YAML block at the top. Supported fields: `title`, `source`, `date`, all optional
* **Detection**: Files with at least one `## User` or `## Assistant` header are recognized as conversations automatically
* **Fallback**: Files without recognized headers are imported as a single document message
* **Case**: Role names are matched case-insensitively (`## user` and `## User` both work)
A complete example with all supported features
## Import API [#import-api]
`POST /threads/import` accepts JSON messages or Conversation Markdown, with single and batch modes.
### Single Thread (JSON messages) [#single-thread-json-messages]
```bash
curl -X POST http://127.0.0.1:14242/threads/import \
-H "Content-Type: application/json" \
-d '{
"title": "My Conversation",
"source": "chatgpt",
"messages": [
{"role": "user", "content": "Hello!"},
{"role": "assistant", "content": "Hi there! How can I help?"}
]
}'
```
### Single Thread (Markdown) [#single-thread-markdown]
```bash
curl -X POST http://127.0.0.1:14242/threads/import \
-H "Content-Type: application/json" \
-d '{
"markdown_content": "## User\n\nHello!\n\n## Assistant\n\nHi there! How can I help?"
}'
```
### Batch Import [#batch-import]
```bash
curl -X POST http://127.0.0.1:14242/threads/import \
-H "Content-Type: application/json" \
-d '{
"threads": [
{
"title": "Thread 1",
"messages": [
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi"}
]
},
{
"title": "Thread 2",
"markdown_content": "## User\n\nGoodbye\n\n## Assistant\n\nSee you!"
}
]
}'
```
Thread IDs are auto-generated when omitted. Titles are inferred from markdown frontmatter when available.
Full request/response schema and field descriptions
## CLI [#cli]
The `nmem` CLI supports thread import from files, JSON, or stdin.
```bash
# Import a conversation markdown file
nmem t import --file conversation.md
# Import with explicit title and source
nmem t import --file chat.md --title "Python Async" --source chatgpt
# Import from JSON messages
nmem t import --messages '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]'
# Bulk JSON from Raycast AI (raycast-ai-exporter output)
nmem t import --file ~/Desktop/raycast_ai_chats.json
# Pipe markdown from stdin
cat conversation.md | nmem t import --stdin --title "Piped Conversation"
```
Run `nmem t import --help` for all options. See the [CLI Reference](/docs/cli) for the full command list.
## Browser Extension [#browser-extension]
The Nowledge Mem Exchange extension works in the browser on **supported AI chat pages**, on the **session you are actually using** with the extension (for example the tab you open in the side panel). It is not a bulk downloader for your entire web chat history; for that, use each vendor’s export plus **Bulk import** in Mem, or see **[Import existing conversations](/docs/import-existing-conversations)**. Auto-capture, manual distill, and backing up the current thread are covered in the [Browser Extension guide](/docs/integrations/browser-extension).
## MCP Tools [#mcp-tools]
| Tool | What it does |
| ------------------------ | ----------------------------------------------------- |
| `thread_search` | Search threads by keywords or list recent threads |
| `thread_fetch_messages` | Fetch full messages from a specific thread |
| `search_thread_messages` | Search within a thread for messages matching keywords |
MCP thread tools search and read threads that already exist in Mem. To capture local coding-agent transcripts, use the native connector for that tool. To backfill older sessions, run `nmem t sync --from ` on the client machine running the agent. Supported sources include `claude-code`, `codex`, `craft-agent`, `cursor`, `gemini-cli`, `grok`, `hermes`, `kimi-code`, `kimi-work`, `mimo-code`, `omp`, `opencode`, and `pi`. That keeps transcript discovery local and uploads the normalized thread to your Mem server.
## Next Steps [#next-steps]
* **[Memories](/docs/memories)**: What happens after distillation: create, search, and organize knowledge
* **[Library](/docs/library)**: Import documents alongside your memories
* **[Browser Extension](/docs/integrations/browser-extension)**: Capture conversations from web AI platforms
* **[Connectors](/docs/integrations)**: Connect your AI tools through native connectors, reusable packages, or MCP
* **[API Reference](/docs/api)**: Full REST API documentation
# Troubleshooting (/docs/troubleshooting)
## All File Locations (Desktop + CLI) [#all-file-locations-desktop--cli]
This is the simplified folder map used by Nowledge Mem:
* **Config/state root**: `co.nowledge.mem.desktop`
* **Data root**: `NowledgeGraph`
* **User workspace**: `ai-now`
* **Client-side tools root** (`nmem` CLI + OpenClaw plugin): `.nowledge-mem`
```text
~/Library/Application Support/co.nowledge.mem.desktop/ # config/state
~/Library/Application Support/NowledgeGraph/ # data (DB/index/logs)
~/ai-now/ # user workspace
~/.nowledge-mem/ # nmem/OpenClaw client config
```
Legacy compatibility paths you may still see:
* `~/Library/Application Support/nowledge-mem/`
* `~/Library/Logs/Nowledge Graph/`
```text
%APPDATA%\co.nowledge.mem.desktop\ # config/state
%LOCALAPPDATA%\NowledgeGraph\ # data (DB/index/logs)
%USERPROFILE%\ai-now\ # user workspace
%USERPROFILE%\.nowledge-mem\ # nmem/OpenClaw client config
```
```text
~/.config/co.nowledge.mem.desktop/ # config/state (XDG_CONFIG_HOME)
~/.local/share/NowledgeGraph/ # data (XDG_DATA_HOME)
~/ai-now/ # user workspace
~/.nowledge-mem/ # nmem/OpenClaw client config
```
Package paths you may also see (depends on install method):
```text
/usr/lib/nowledge-mem/
/usr/share/nowledge-mem/
```
Legacy compatibility paths you may still see:
* `~/.local/share/co.nowledge.mem.desktop/`
* `~/.local/share/Nowledge Graph/`
* `~/.local/share/nowledge-mem/`
## Viewing Logs [#viewing-logs]
Open **Settings → Info → Show Log Files** to reveal the log folder directly in Finder or Explorer. No terminal required.
If the app fails during startup, the error screen includes a **Show Logs** button that does the same thing.
On macOS, the canonical system log file is located at `~/Library/Application Support/NowledgeGraph/Logs/app.log`.
You can view it by running this command in your terminal:
```bash
open -a Console ~/Library/Application\ Support/NowledgeGraph/Logs/app.log
```
If you upgraded from an older build, you may still have a legacy log path:
```bash
open -a Console ~/Library/Logs/Nowledge\ Graph/app.log
```
On Windows, the system log file is located on two possible locations based on the installation method:
* `%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.log` (installed from Microsoft Store)
* `%LOCALAPPDATA%\NowledgeGraph\logs\app.log` (installed from package file downloaded from Nowledge Mem website)
You can view it by pasting this into address bar of File Explorer:
```shell
%LOCALAPPDATA%\Packages\NowledgeLabsLLC.NowledgeMem_1070t6ne485wp\logs\app.log
```
or this:
```shell
%LOCALAPPDATA%\NowledgeGraph\logs\app.log
```
## Search And Index Health [#search-and-index-health]
If your issue is about search quality or search-index disk usage, start here first:
* Open **Settings -> Memory Processing -> Search**
* Use **Optimize** when the search index takes too much disk space
* Use **Rebuild Index** when search results look clearly incomplete, stale, or badly ranked
The storage line in that panel separates the main parts of your local data:
* **Knowledge Graph**: memories, entities, relationships, and graph metadata
* **Messages**: saved conversation messages and larger text payloads
* **Search Index**: a rebuildable search projection used for ranking and snippets
These two actions solve different problems:
* **Optimize** compacts on-disk search storage without rebuilding everything
* **Rebuild Index** recreates the search index from your saved memories, library content, and message store when the existing index may be stale or corrupted
If you are on a Linux server or using Mem remotely without the desktop app open:
* Run `nmem status` to see whether search is ready, needs a rebuild, or is only updating metadata
* Run `nmem models status` for the same signal plus model installation state
* If the status says **updating metadata**, let it finish. That path does not need a rebuild.
When the search index is stale (for example after you switch embedding providers or models), Mem does not error or return 500s. It falls back to keyword (FTS) search while the index catches up, and `GET /health` reports `reindex_needed: true`. Trigger the rebuild from **Settings → Memory Processing → Search** when you are ready; search keeps working the whole time.
If semantic results feel weak even when the index is current, check `embedding.mode` in `GET /health`. A value of `local-hash-fallback` means no real embedder is configured, so only keyword search is fully working. Set a remote embedding provider or download the local model to restore semantic search.
## App Takes Too Long to Start [#app-takes-too-long-to-start]
**Symptom:** The app hangs or shows a timeout error during startup.
**Solution:** Global proxies or VPN software can prevent the app from accessing `http://127.0.0.1:14242` directly.
Configure your proxy or VPN tool to bypass localhost addresses. Add the following to your bypass/exclusion rules:
```
127.0.0.1, localhost, ::1
```
This allows you to keep your proxy/VPN enabled while ensuring Nowledge Mem can communicate with its local server. After updating the bypass rules, restart Nowledge Mem.
## Windows Startup Fails: Missing Visual C++ Runtime [#windows-startup-fails-missing-visual-c-runtime]
**Symptom:** On startup, `app.log` shows:
* `Import error: DLL load failed while importing _lbug`
* or `Backend exited during startup readiness check: exit code: 1`
**Cause:** A required Microsoft C++ runtime dependency is missing for the bundled database engine.
**Fix:**
1. Download and install **Microsoft Visual C++ Redistributable (x64)**:
[https://aka.ms/vs/17/release/vc\_redist.x64.exe](https://aka.ms/vs/17/release/vc_redist.x64.exe)
2. Restart Nowledge Mem.
3. If it still fails, attach `app.log` when reporting the issue.
## AI Now Session Fails to Start [#ai-now-session-fails-to-start]
**Symptom:** Clicking **New Task** or resuming a paused task fails, and AI Now cannot open a session.
**What to do first:** Check the startup diagnostics card shown in AI Now.
When startup fails, AI Now now shows a diagnostics card with:
* failure stage (`spawn`, `initialize`, or `new_session`)
* platform and process exit code
* recent `stderr` output from the startup script
* a copy button for sharing diagnostics
Click **Details** to expand technical fields, then click **Copy diagnostics** for support or issue reports.
**Common fixes (especially on Windows):**
1. Verify your installation is complete (embedded Python and startup scripts are present).
2. Restart Nowledge Mem after plugin or model configuration changes.
3. Update to the latest build if you use Windows and have shell customizations like Conda. Recent releases isolate AI Now and the bundled `nmem` launcher from broken PowerShell profile hooks so those scripts no longer fail before Mem starts.
4. Temporarily disable antivirus/quarantine rules that may block bundled Python or PowerShell startup.
5. If a plugin is involved, reconnect expired OAuth plugins in **AI Now → Plugins** and retry.
### Optional: Open Developer Console on Windows (Hotkey) [#optional-open-developer-console-on-windows-hotkey]
If AI Now is still stuck and you need extra startup logs, use the built-in Windows hotkey:
* Press Ctrl + Shift + I to toggle the Tauri/WebView console.
* Go to the **Console** tab.
* Filter logs with keywords like `[AI Now]`, `[ACP]`, or `[kimi-cli stderr]`.
This works for both Microsoft Store installs and website installer builds.
Then reproduce the issue by opening AI Now and clicking **New Task**.
If it still fails, include copied diagnostics plus `app.log` when reporting the issue.
## Corrupted Model Cache [#corrupted-model-cache]
**Symptom:** Search, memory distillation, or knowledge extraction features stop working unexpectedly.
**Solution:** Clear the model cache and re-download the models.
Navigate to Settings → Models, and click:
After clearing the cache, re-download the required models.
## Search Index Uses Too Much Disk Space [#search-index-uses-too-much-disk-space]
**Symptom:** Search works, but the search index size in **Settings -> Memory Processing -> Search** looks much larger than expected.
**What to do:** Click **Optimize** in that same panel.
**Optimize** compacts the search index on disk and flushes database changes. It does not delete memories or saved conversations.
From v0.6.8 onward, and more aggressively for the native LanceDB search index used in 0.9.0, this can shrink storage dramatically on machines with older index versions left behind. In real cases, users may see something like **5 GB -> 300 MB** after compaction.
**When to use it:**
1. The index keeps growing after updates or repeated reindexing.
2. The search index is much larger than the knowledge you actually store.
3. Search still works, but disk usage looks obviously wasteful.
If the **Search Index** number still looks wrong after optimization, run **Rebuild Index** once. If the **Messages** number is large, that usually means you have imported or saved many conversations; use [Data Transfer](/docs/data-portability) for backup and migration rather than deleting index files by hand. If storage remains abnormal, include a screenshot of the **Memory Processing** panel when reporting the issue.
## Search Ranking Looks Obviously Wrong [#search-ranking-looks-obviously-wrong]
**Symptom:** Search returns clearly bad matches, misses memories that should be easy to find, or feels much worse than before.
**What to do:** Open **Settings -> Memory Processing -> Search** and click **Rebuild Index**.
Rebuilding recreates the full search index from your saved memories, library content, and message store.
This is the right recovery step when an interrupted write, stale index state, or another indexing issue has left search quality obviously degraded.
**Try this when:**
1. A memory exists, but search cannot find it with reasonable queries.
2. Results are suddenly much worse after an upgrade, crash, or heavy import.
3. Ranking looks clearly inconsistent with what you know is already in Mem.
After reindexing finishes, rerun the same query. If the ranking is still clearly wrong, send the query example and the expected memory when reporting the issue.
## Windows: PATH Corrupted After Install or Upgrade [#windows-path-corrupted-after-install-or-upgrade]
**Symptom:** After installing or upgrading Nowledge Mem, other command-line tools stop working. Running `pnpm`, `git`, `node`, or similar commands returns "not recognized" or "command not found". Checking your user PATH shows it has been reduced to just `C:\Users\...\Nowledge Mem\cli` or has lost entries like `%PNPM_HOME%`.
**Cause:** Versions before 0.6.8 could overwrite your Windows user PATH during installation by expanding environment variable references (like `%PNPM_HOME%`) into literal paths, or in some cases replacing the entire PATH with just the Nowledge Mem CLI directory.
**This is fixed in 0.6.8 and later.** The installer now preserves your PATH entries and their environment variable references exactly as they were.
**If you were affected, here is how to restore your PATH:**
1. Press Win + R, type `sysdm.cpl`, and press Enter.
2. Go to **Advanced** > **Environment Variables**.
3. Under **User variables**, select **Path** and click **Edit**.
4. Re-add any missing entries. Common ones include:
* `%PNPM_HOME%`
* `%USERPROFILE%\AppData\Local\Programs\Microsoft VS Code\bin`
* `%USERPROFILE%\.cargo\bin`
* `%USERPROFILE%\AppData\Roaming\npm`
5. Click **OK** and open a new terminal window.
If you're not sure what your PATH should contain, check a working machine or refer to the installation docs of each tool you use (pnpm, Node.js, Rust, etc.). Each tool's installer typically documents which PATH entry it adds.
## Windows: Memories Missing After Update (Even After Rolling Back) [#windows-memories-missing-after-update-even-after-rolling-back]
**Symptom:** After a Windows update, your memory count drops to zero or near zero. Rolling back to the previous version does not bring them back.
**Your data is not lost.** Your graph lives in one folder, but the app is now reading a different location where an empty database got created, and that empty one is shadowing your real data. The steps below move the real data back to where the app looks. You only copy or rename, never delete, so a wrong guess is always reversible.
**Before you start:** Fully quit Nowledge Mem, including from the system tray. Open Task Manager and confirm no `nmem-server` or Nowledge Mem process is still running.
**Step 1: Find the real data.**
Press Win + R and open each of these in turn. Some may not exist, and that is fine:
* `%LOCALAPPDATA%\NowledgeGraph` (what the app reads now, usually the empty one)
* `%APPDATA%\NowledgeGraph` (older location, real data is often here)
* `%USERPROFILE%\Documents\NowledgeGraph` (oldest location)
In each folder, compare the size of `nowledge_graph_v2.db`. Real data is tens of MB to several GB. A fresh empty database is small and was last modified on the day things broke. Also check whether a sizeable `content.db` and any `content.db.backup.*` files are present. The folder with the largest and oldest `nowledge_graph_v2.db` is your real data folder.
**Step 2: Back up the current (empty) location.**
In `%LOCALAPPDATA%`, rename the `NowledgeGraph` folder to `NowledgeGraph_empty_backup`. Rename it, do not delete it.
**Step 3: Copy the real data into place.**
Copy your real data folder into `%LOCALAPPDATA%\` so that it is named `NowledgeGraph`. Copy it, do not move it, so the original stays as a backup.
**Step 4: Start the app.**
Open Nowledge Mem and go to Memories. The count should return.
Updating to 0.10.6 (or 0.10.5) makes the app auto-find and open your data from these old locations, as long as the current location is still empty, meaning you have not saved any new memories into the empty one.
**Still stuck, or not comfortable doing this by hand:** Take a screenshot of the `nowledge_graph_v2.db` sizes in the three folders and email them, together with your `app.log` (from **Settings → Info**), to [hello@nowledge-labs.ai](mailto:hello@nowledge-labs.ai). Do not delete any `NowledgeGraph` or `_empty_backup` folder before you hear back.
## Backend Won't Start / Crash Loop (Quarantine a Corrupt Database Journal) [#backend-wont-start--crash-loop-quarantine-a-corrupt-database-journal]
**Symptom:** After an update or an interrupted rebuild, the app never finishes starting and the backend keeps restarting. Sometimes a hard crash or a power loss during a write leaves the database write-ahead journal (`.wal`) in a bad state, and the backend cannot open the graph.
Nowledge Mem already tries to recover from this automatically on launch: it moves a corrupt journal aside and reopens the graph. The manual step below is only for the rare case where that automatic recovery did not run.
**Steps:**
1. Fully quit the app, including from the system tray.
2. Open the graph data folder for your platform:
* macOS: `~/Library/Application Support/NowledgeGraph`
* Windows: `%LOCALAPPDATA%\NowledgeGraph`
* Linux: `~/.local/share/NowledgeGraph`
3. If a file named `nowledge_graph_v2.db.wal` exists, rename it to `nowledge_graph_v2.db.wal.corrupt-backup`. Rename it, do not delete it.
4. If `nowledge_graph_v2.db.shm` is present, rename it aside as well.
5. Start the app.
Only the most recent, not-yet-saved changes can be affected. Everything already saved is intact. If it still will not start, send your `app.log` to [hello@nowledge-labs.ai](mailto:hello@nowledge-labs.ai) and keep the renamed files.
## CLI Not Found [#cli-not-found]
**Symptom:** Running `nmem` in terminal returns "command not found".
**Solutions by platform:**
* **macOS**: Open Nowledge Mem once, then open a new terminal. The app installs
or repairs `nmem` after startup without blocking the app. If the command is
still missing, use **Settings → Preferences → Developer Tools → Install CLI**
to repair it manually.
* **Windows**: Open a **new** terminal window after app installation (the PATH update requires a fresh session)
* **Windows (WSL)**: See the [WSL setup](#using-nmem-from-wsl) section below
* **Linux**: Desktop packages include the CLI and the app repairs the wrapper
after startup. Open a new terminal; if `nmem` is still missing, make sure
`~/.local/bin` is in your shell PATH.
**Quick check:** Run `nmem status` to verify the CLI can connect to Nowledge Mem.
## CLI and Server Versions Differ [#cli-and-server-versions-differ]
**Symptom:** `nmem status` shows "Version mismatch".
This means the command in your terminal and the Mem server it reached were installed or updated separately. The connection can still be healthy, but an older CLI may not know the latest commands or diagnostics.
**Fix the side that is older:**
* **Desktop CLI:** Open **Settings → Preferences → Developer Tools → Install CLI**, then restart the terminal.
* **PyPI install:** Run `python -m pip install --upgrade nmem-cli`.
* **pipx install:** Run `pipx upgrade nmem-cli`.
* **One-shot use:** Run `uvx --from nmem-cli nmem status`.
* **Server older than CLI:** Update or restart Nowledge Mem, or check that `NMEM_API_URL` points to the server you meant to use.
## Using nmem from WSL [#using-nmem-from-wsl]
If you run coding agents like Claude Code or Codex inside WSL on Windows, the Windows `nmem` CLI isn't directly available in the Linux environment.
**From v0.6.9**, clicking **Install CLI** in Settings automatically creates a lightweight shim inside your default WSL distribution. If you need to set it up manually, paste this into your WSL terminal:
```bash
mkdir -p ~/.local/bin && cat > ~/.local/bin/nmem << 'SHIMEOF'
#!/usr/bin/env bash
cd /mnt/c || exit 1
exec cmd.exe /c nmem.cmd "$@"
SHIMEOF
chmod +x ~/.local/bin/nmem
```
This creates a thin wrapper that calls the Windows `nmem` via interop from a Windows-mounted working directory. That avoids the common UNC-path failure mode from WSL home directories. Since the command runs as a Windows process, it connects to the desktop app on `localhost` directly, so no extra network configuration is needed.
**Verify it works:**
```bash
nmem status
```
If `nmem` is still not found after creating the shim, make sure `~/.local/bin` is in your PATH. On Ubuntu this happens automatically; on other distributions, add `export PATH="$HOME/.local/bin:$PATH"` to your `~/.bashrc` or `~/.zshrc`.
This approach requires WSL interop (enabled by default). If you've set `interop=false` or `appendWindowsPath=false` in `/etc/wsl.conf`, re-enable them or use `pip install nmem-cli` with [Access Mem Anywhere](/docs/remote-access) instead.
The shim runs `nmem` as a Windows process, so commands like `nmem t save --from claude-code` look for session files in your Windows home directory rather than your WSL home. This is fine in practice: the desktop app captures WSL sessions automatically through its built-in file watcher. If you need direct CLI thread capture from WSL, use `pip install nmem-cli` instead.
## nmem status Returns "Not Found" [#nmem-status-returns-not-found]
**Symptom:** `nmem status` shows "Not Found: Resource doesn't exist" when using a remote server, but the TUI works fine.
**Cause:** The CLI is hitting the wrong URL. This usually means `~/.nowledge-mem/config.json` is missing or has the wrong `apiUrl`.
**Fix:**
1. Verify the config file exists and has the correct URL:
```json title="~/.nowledge-mem/config.json"
{
"apiUrl": "https://",
"apiKey": "nmem_..."
}
```
2. Test with curl: `curl -H "Authorization: Bearer $NMEM_API_KEY" "$NMEM_API_URL/health"`
3. Update to the latest `nmem` CLI. Newer versions show clearer error messages and remote setup hints.
Full setup: [Access Mem Anywhere](/docs/remote-access).
## Remote Access Returns 429 [#remote-access-returns-429]
**Symptom:** `nmem status` or `curl` returns `429 Too many invalid auth attempts`.
**Solution:** The client retried with an invalid API key too many times.
* Re-copy URL + key from **Settings → Access Mem Anywhere**
* Ensure `NMEM_API_KEY` is the exact value (no extra spaces/quotes)
* If unsure, click **Rotate** to issue a new key
Full setup and validation steps: [Access Mem Anywhere](/docs/remote-access).
## Remote Access Returns 401 Missing API key [#remote-access-returns-401-missing-api-key]
**Symptom:** Tunnel URL is reachable, but `nmem status` or `curl` returns `401 Missing API key`.
**Cause:** Some network proxies remove auth headers.
**Fix:**
* Update to latest `nmem` (it retries with proxy-safe fallback automatically)
* Re-copy URL + key from **Settings → Access Mem Anywhere**
* For manual `curl`, verify with:
`curl "$NMEM_API_URL/health?nmem_api_key=$NMEM_API_KEY"`
## Mem Says Graph Memory Was Increased [#mem-says-graph-memory-was-increased]
**Symptom:** Search, graph, or save operations start failing on a larger library, and Mem shows a title-bar notice that graph memory was updated.
**Cause:** Mem raised the graph-memory limit for the next launch after the current session ran out of room. The running backend is still on the old limit until you reopen the app.
**Fix:**
1. Quit and reopen Nowledge Mem. That applies the higher graph-memory limit.
2. If the notice keeps coming back, open **Settings → Processing → Database Tuning** and choose a larger **Graph Memory** value.
3. On headless or server installs, set `NOWLEDGE_KUZU_BUFFER_POOL_SIZE=512MB` (or higher) before starting `nmem serve`.
## Mem Looks Like It Uses a Lot of RAM [#mem-looks-like-it-uses-a-lot-of-ram]
**Symptom:** Activity Monitor (macOS) or Task Manager (Windows) shows Nowledge Mem using around a gigabyte of memory, which looks high for a notes-and-memory app.
**This is normal, and the number is misleading.** The figure your system monitor shows is not how much memory Mem actually needs. Most of it falls into three buckets that do not count as real pressure on your machine:
* **Memory we have already finished with.** After bursts of work like search, importing, or background processing, your operating system keeps those pages parked with Mem instead of reclaiming them right away, because handing them back and forth is slow. They are free to be reused the moment anything else needs them.
* **Shared program code.** Mem ships as a single self-contained app, so its program code shows up in the memory number, but it is shared and read-only and the system drops it instantly under pressure.
* **Your knowledge stored on disk.** Your graph and search index live as files on disk. The system counts them toward Mem's memory because it maps them in for fast reads, but they are not really sitting in RAM, and they are released as needed.
Mem's actual working memory is well under what the headline number suggests, and it holds **no AI model in memory unless you are running a local model**.
You do not need to take any action. If your machine genuinely runs low on memory, the system reclaims most of this automatically. An upcoming update also changes how Mem returns idle memory to the system, so the reported number will get smaller on its own.
The actual measurement, if you want to verify
Measured on a real library of about 2,100 memories, sitting idle, using each operating system's own tools. The takeaway is the same everywhere: the headline number is much larger than the memory actually in use.
**macOS**: reproduce with `footprint ` or `vmmap -summary ` against the `nmem-server` process:
| What | Size |
| ----------------------------------------------- | ------------------- |
| Reported memory (`phys_footprint`) | \~1024 MB |
| Shared program code (read-only, reclaimable) | \~281 MB |
| Database file mapped in (lives on disk) | \~0.3 MB resident |
| Already-freed memory not yet returned to the OS | \~500 MB |
| Real in-use memory | the small remainder |
On a Mac, Mem runs the local embedding model on the GPU, so its working buffer stays off the main number and the figure above is mostly reclaimable.
**On a computer without a usable GPU** (some Windows and Linux setups, or a headless server), the local embedding model runs on the CPU instead and reserves a larger working buffer, so the number is genuinely higher there (measured around 4-5 GB). This only applies when you run the embedding model **locally on the CPU**. The easiest way to avoid it is to use a **remote embedding model**, which keeps this buffer off your machine entirely: **Nowledge AI** (included with Mem Plus) works with no setup, or you can connect your own embedding provider with your own key. Running the local model on a machine with a GPU also keeps it small. We are additionally shrinking the local CPU buffer in an upcoming update.
## Linux Server Setup Says It Cannot Reach 127.0.0.1:14242 [#linux-server-setup-says-it-cannot-reach-12700114242]
**Symptom:** Commands like `nmem license activate`, `nmem models download`, or `nmem config ...` fail with “Cannot reach [http://127.0.0.1:14242”](http://127.0.0.1:14242”).
**Cause:** Those commands talk to your local Mem server. On a fresh Linux server, that usually means the server is not running yet, or you started it in the foreground and forgot you still need a second terminal.
**Fix:**
1. For a real server, install the background service first: `sudo nmem service install --service-user `
2. Then verify it is up: `nmem service status` and `nmem status`
3. If you are only doing a quick test with `nmem serve`, keep that terminal open and run the other `nmem` commands in a second terminal
4. To open the web app from your own computer over SSH, run `nmem key --show-login` first and forward the same port it prints: `ssh -L :127.0.0.1:`
5. To print the login key again, run `nmem key --show-login` on newer builds, or `nmem key` on older ones
## Report Issue [#report-issue]
# Try These (/docs/try-these)
Your Timeline input handles everything: questions, captures, URLs, files, scheduling. Type naturally and AI figures out the rest. Here are the queries that show what the system can really do.
These queries get more powerful as your knowledge grows. After a week of regular use, the results will surprise you.
## The Queries [#the-queries]
### Show my Working Memory briefing [#1-show-my-working-memory-briefing]
Reads your current focus surface. What topics are active, what needs attention, and what changed recently. Native integrations and well-configured agents can load the right Working Memory briefing automatically at session start.
### Which of my ideas have evolved the most? [#2-which-of-my-ideas-have-evolved-the-most]
Finds the longest EVOLVES chains, ideas that went through multiple revisions. Tells the story chronologically: "In January you decided on PostgreSQL. By March, you were considering a hybrid approach. Your latest note confirms the dual-database migration."
### What wisdom has crystallized from my notes? [#3-what-wisdom-has-crystallized-from-my-notes]
Shows synthesized crystals, reference articles the system distilled from multiple related memories overnight. These are the insights you couldn't get from any single note.
### Summarize my recent coding conversations [#4-summarize-my-recent-coding-conversations]
If your coding sessions are already flowing into Mem through local auto-sync, native save paths, or thread import, this lists and summarizes the latest ones: what was discussed, what was built, what decisions were made.
### Just decided to use PostgreSQL for the main database [#5-just-decided-to-use-postgresql-for-the-main-database]
Knowledge capture. The system saves it as a memory, searches for related decisions, and mentions connections: "This relates to your earlier note about database scaling." Just type naturally, the AI classifies what you share and stores it.
### Save `https://example.com/interesting-article` [#6-save-httpsexamplecominteresting-article]
Paste a URL and the system fetches, parses, and indexes the content. AI reads the page and stores a substantive summary as a memory. The URL and its content become searchable. Add a note before the URL and AI captures both.
### Tonight, run knowledge graph extraction on my recent memories [#7-tonight-run-knowledge-graph-extraction-on-my-recent-memories]
Schedule a Background Intelligence task. The agent fires at the specified time with full tool access: it can analyze memories, detect contradictions, create EVOLVES links, or produce crystals. Natural language timing: "in 2 hours", "tomorrow morning", "next week". Min 5 minutes, max 30 days.
### Search my documents for \[topic] [#8-search-my-documents-for-topic]
Full-text search across all source documents in your Library. Drop files (PDF, Word, markdown) onto the Timeline input or add them through the Library. They get parsed, chunked, and indexed for semantic search.
### What are my main knowledge themes? [#9-what-are-my-main-knowledge-themes]
**Note**: This requires a week of regular use and background processing.
Community detection clusters your entities into topic areas with AI summaries. The system runs overnight analysis to group related concepts. You'll see themes you never consciously tracked: a "developer experience" cluster you didn't know existed, or a "data architecture" theme threading through months of notes.
## The Compound Effect [#the-compound-effect]
These queries get more powerful over time:
* **Week 1**: Basic search works. Communities are small or empty.
* **Month 1**: Evolution chains appear. Crystals start forming. Themes emerge.
* **Month 3**: Cross-domain connections surprise you. Daily briefings are genuinely useful.
* **Month 6**: The system knows your expertise better than you can articulate it.
## Next Steps [#next-steps]
* [Getting Started](/docs/getting-started): Set up in five minutes
* [See Your Expertise](/docs/use-cases/expertise-graph): Explore the knowledge graph visually
* [Background Intelligence](/docs/advanced-features): How the system learns overnight
# Using Nowledge Mem (/docs/usage)
Go back to [Start Here](/docs/start-here) and [How To Know Mem Is Working](/docs/verify-it-works). This page makes more sense once you have already proven one real workflow.
## The Timeline [#the-timeline]
The Timeline is your home screen. Everything lives here: what you capture, what you ask, what the system discovers on its own.
### What You'll See [#what-youll-see]
| Item | What it is |
| ------------------ | ------------------------------------------------------------- |
| **Capture** | A memory you saved, with auto-generated title and tags |
| **Question** | Your question and the AI's answer, drawn from your knowledge |
| **URL Capture** | A web page fetched, parsed, and stored |
| **Insight** | A connection the system discovered between your memories |
| **Crystal** | A crystal synthesizing multiple related memories |
| **Flag** | A contradiction, stale info, or claim that needs verification |
| **Working Memory** | Your daily morning briefing |
## Your AI Tools [#your-ai-tools]
Connect the AI tools you actually use to your knowledge. Claude Code, Grok Build, Cursor, Codex, OpenCode, Alma, DeepChat, LobeHub, Grok Web, and more can all point back to the same memory system through the right path.
If you are still deciding how to connect a tool, go to [Connectors](/docs/integrations) first. This page is about what Mem feels like after one setup path is already working.
**Without Mem:** *"Help me implement caching for the API."* Your agent often asks about your stack, your infrastructure, and your preferences. You explain everything from scratch.
**With Mem:** *"Help me implement caching for the API."* Your agent can search your knowledge, find your Redis decision from last month and your API rate limiting patterns, and write code that fits your architecture with much less repeated setup.
In the best-integrated setups, this happens without prompting. Native integrations, well-configured reusable workflow packages, and MCP clients with clear intent rules can recognize when your knowledge is relevant and use it automatically.
Save an insight in Claude Code today. Cursor finds it tomorrow when it encounters the same topic. No copying, no exporting.
You can also query directly: *"What did I decide about database migrations last month?"* Your agent searches your knowledge to answer.
See [Connectors](/docs/integrations) for setup instructions.
## Search [#search]
### In the App [#in-the-app]
Open memory search with Cmd + K (macOS). Search understands meaning, not just keywords. Searching "design patterns" finds memories about "architectural approaches."
Three search modes work together:
* **Semantic** finds memories by meaning
* **Keyword** does exact match for specific terms
* **Graph** discovers memories through entity connections and topic clusters
### From Anywhere [#from-anywhere]
Press Cmd + Shift + K from any application to search without opening Nowledge Mem. Copy results directly where you need them. The [Raycast extension](/docs/integrations/raycast) brings the same search into your launcher.
## What Happens Over Time [#what-happens-over-time]
After a few weeks of daily use, the system starts working for you in the background.
You save a decision about PostgreSQL on Tuesday. On Thursday, you mention CockroachDB as a migration target. Friday morning, Working Memory notes: "Your database thinking is evolving."
This is **Background Intelligence**:
* **Knowledge evolution.** Detects when your thinking on a topic changes and links the versions.
* **Crystals.** Synthesize scattered memories into reference articles.
* **Flags.** Surfaces contradictions between past and present thinking.
* **Working Memory.** A daily briefing your AI tools read at session start.
Background Intelligence requires a configured Remote LLM and the appropriate license for your build.
## AI Now [#ai-now]
A personal AI workspace connected to your Mem server. It can use your saved knowledge, connected notes, files, and enabled plugins, and the same sessions are available from desktop, web, and mobile clients. See [AI Now](/docs/ai-now) for the full guide.
## Command Line [#command-line]
The `nmem` CLI gives full access from any terminal:
```bash
# Search your memories
nmem m search "authentication patterns"
# Add a memory
nmem m add "We chose JWT with 24h expiry for the auth service"
# JSON output for scripting
nmem --json m search "API design" | jq '.memories[0].content'
```
See the [CLI reference](/docs/cli) for the complete command set.
## Remote LLMs [#remote-llms]
By default, everything runs locally. No internet required. As your knowledge base grows, a remote LLM gives you stronger processing.
Remote LLM configuration depends on the license and build you are using.
**What it unlocks:**
* **Background Intelligence**: automatic connections, crystals, insights, and daily briefings
* Faster knowledge graph extraction
* More nuanced semantic understanding
* AI Now agent capabilities
**Privacy:** your data is sent only to the LLM provider you choose. Never to Nowledge Mem servers. Switch back to local-only at any time.
### Open Remote LLM settings [#open-remote-llm-settings-step]
Go to **Settings > Remote LLM**
### Enable remote mode [#enable-remote-mode-step]
Toggle **Remote** to enable
### Add provider and API key [#add-provider-and-api-key-step]
Select your LLM provider and enter your API key
### Test, pick a model, and save [#test-pick-a-model-and-save-step]
Test the connection, select a model, and save
## Next Steps [#next-steps]
* **[Start Here](/docs/start-here)**: Pick the simplest path for your real workflow
* **[How To Know Mem Is Working](/docs/verify-it-works)**: Confirm search, capture, and connected tools
* **[Memories](/docs/memories)**: Create, search, organize, and connect your knowledge
* **[Threads](/docs/threads)**: Capture, browse, and distill AI conversations
* **[Library](/docs/library)**: Import documents alongside your memories
* **[AI Now](/docs/ai-now)**: Deep research and analysis powered by your knowledge
* **[Background Intelligence](/docs/advanced-features)**: Knowledge graph, insights, crystals, working memory
* **[Your Profile](/docs/profile)**: Tell Mem who you are so agents give better results
* **[Connectors](/docs/integrations)**: Choose the right connection path for each AI tool
# How To Know Mem Is Working (/docs/verify-it-works)
Mem is working when you can point to one result and say:
* that came from my own knowledge
* that thread was really captured
* that tool really used my saved context
This page is for proving that, quickly.
## The Core Test [#the-core-test]
Before testing any connector, prove the app loop first:
### Save One Memory [#save-one-memory-step]
In the Timeline, write one real fact, decision, or preference and press Enter.
### Ask For It Back [#ask-for-it-back-step]
Ask a direct question about that memory:
> What did I decide about deployment?
### Look For A Grounded Answer [#look-for-a-grounded-answer-step]
Mem is working if the answer clearly reflects what you saved instead of giving a generic answer.
## If You Use The App Only [#if-you-use-the-app-only]
You should be able to do all three:
* save a memory in the Timeline
* search for it again
* ask a question that is answered from your own knowledge
If that loop works, the base product is working.
## If You Use The Browser Extension [#if-you-use-the-browser-extension]
Mem is working when all of these are true:
* the extension can open its side panel
* connection testing succeeds if you are using remote access
* one captured or distilled web conversation shows up in Mem
* you can open that saved result from the app as a memory or a thread
If you have not reached that state yet, go to the [Browser Extension guide](/docs/integrations/browser-extension).
## If You Use A Coding Assistant [#if-you-use-a-coding-assistant]
Mem is working when your tool can use context you already saved.
Try this:
1. Save a short decision in Mem, such as your preferred caching approach.
2. Open your coding assistant through its dedicated connector.
3. Ask a question that should benefit from that saved context.
Examples:
* "What did I decide about caching for this service?"
* "Continue the approach I used before for authentication."
* "Search my prior decisions about Redis."
You have a real working connection when the tool recalls your knowledge instead of asking you to restate everything from scratch.
Use the matching guide:
* [Claude Code](/docs/integrations/claude-code)
* [Cursor](/docs/integrations/cursor)
* [Gemini CLI](/docs/integrations/gemini-cli)
* [Copilot CLI](/docs/integrations/copilot-cli)
* [OpenClaw](/docs/integrations/openclaw)
* [Alma](/docs/integrations/alma)
* [Codex](/docs/integrations/codex-cli)
## If You Use AI Now [#if-you-use-ai-now]
AI Now is working when:
* your Remote LLM is configured if required for the feature you are using
* you ask a question about your own saved knowledge
* the answer is grounded in your memories, files, or enabled plugins rather than sounding generic
If AI Now cannot start or cannot answer from your saved context, check [AI Now](/docs/ai-now) and [Troubleshooting](/docs/troubleshooting).
## If You Use Mem Across Multiple Devices [#if-you-use-mem-across-multiple-devices]
Your sync setup is working when all of these are true:
* the second device connects successfully with the same Mem URL and API key
* a memory or thread created on one client appears on the other client
* search results on both clients reflect the same knowledge base
If you are unsure what model Mem uses here, read [Sync Across Devices](/docs/sync). For setup details, read [Access Anywhere](/docs/remote-access).
## Good Signs [#good-signs]
* Search returns your own wording, decisions, or references
* A captured conversation appears in Threads
* Your connected tool can recall a prior decision without you pasting it again
* AI Now can answer based on your saved knowledge
## Warning Signs [#warning-signs]
* You only get generic model output with no sign of your saved context
* You configured many paths, but none produced one visible result
* You are testing MCP or CLI before verifying the app itself
* You expect browser capture, coding-agent save, and AI Now to all prove themselves at the same time
## If It Still Feels Unclear [#if-it-still-feels-unclear]
Go back to one path only:
1. [Start Here](/docs/start-here)
2. Save one memory in the Timeline
3. Verify the app loop
4. Connect only one real tool
## Next Steps [#next-steps]
* [Start Here](/docs/start-here): Pick the right first path
* [Getting Started](/docs/getting-started): Learn the Timeline workflow
* [Connectors](/docs/integrations): Connect the right tool the right way
* [Sync Across Devices](/docs/sync): Understand the single-Mem, multi-client sync model
* [Troubleshooting](/docs/troubleshooting): Diagnose startup, connection, and session issues
# API Reference (/docs/api)
The Nowledge Mem server exposes a local REST API on port `14242`. Every feature in the desktop app and MCP tools uses these same endpoints, so you can build your own connectors, scripts, and automations on top of the same data.
Base URL: `http://127.0.0.1:14242`
***
## Graph Visualization [#graph-visualization]
Open an interactive, force-directed knowledge graph right in your browser — no desktop app required.
## Memories [#memories]
Create, search, and manage your knowledge base.
#### Count semantics [#count-semantics]
Counts are reported per lifecycle state, so different views can differ without anything being lost. On `/stats`, `memory_count` is the **active** working set (what `/memories` returns by default and what the Memories page shows). The full picture is broken out as `memory_archived_count` (superseded and retired memories, kept in history), `memory_stored_count` (active + archived), and `crystal_count` (synthesized summaries, counted separately). The `/memories` `state` query param selects the lens: `active` (default), `archived`, or `all`.
### Knowledge Extraction [#knowledge-extraction]
Extract entities and relationships from memory content into the knowledge graph.
### Distillation [#distillation]
Turn conversation threads into structured memories.
## Threads [#threads]
Import, search, and manage conversation threads from Claude Code, Codex, Cursor, and more.
### Session Import [#session-import]
Auto-discover and import coding sessions from AI assistants.
### Import Configuration & Watcher [#import-configuration--watcher]
## Background Intelligence [#background-intelligence]
The background agent that runs daily briefings, crystallization, insight detection, and more.
### Agent Triggers [#agent-triggers]
Manually trigger agent tasks that normally run on a schedule.
### Feed Events [#feed-events]
The event stream powering the desktop Feed view.
## Nowledge FS [#nowledge-fs]
Browse Mem as a path-first tree for scripts, web clients, and agents.
## Spaces [#spaces]
Manage shared space profiles and discover the current roster across clients.
## Sources (Library) [#sources-library]
Ingest files, URLs, and documents into the knowledge base.
### Ingestion [#ingestion]
## Graph Analysis & Maintenance [#graph-analysis--maintenance]
Advanced graph operations — community detection, centrality, orphan cleanup.
## Labels & Organization [#labels--organization]
## Favorites [#favorites]
## Skills [#skills]
Procedural memory: skills born from your evidence, proven before they run, sharpened with use.
## Entities & Communities [#entities--communities]
## Models & Search Index [#models--search-index]
Manage the embedding models and search infrastructure.
## Storage & Data [#storage--data]
## System [#system]
## Embeddings (OpenAI-compatible) [#embeddings-openai-compatible]
Drop-in replacement for OpenAI's embedding API, powered by the local model.
# AI Profiles (/docs/concepts/ai-profiles)
An AI Profile is a stable identity for an agent that works for you over time.
Use one when an agent is more than a one-off chat: a reviewer, a researcher, a release helper, a writing partner, or a worker launched by a multi-agent tool. The profile tells Mem who that agent is, which memory space it usually belongs to, and which rules should shape its behavior before it starts working.
## Why this exists [#why-this-exists]
AI tools already have many places to keep behavior: `AGENTS.md`, `CLAUDE.md`, Cursor rules, Codex profiles, Hermes souls, and host-specific settings. That works until you have several agents and several hosts. Then "Codex" is not enough information. Codex may be running your reviewer today and your release helper tomorrow.
Mem separates two facts:
| Field | What it means |
| -------------- | ----------------------------------------------------------------------------- |
| **AI Profile** | Which long-running agent is working, such as `cindy` or `release-reviewer` |
| **Source app** | Which runtime produced the event, such as `codex`, `claude-code`, or `hermes` |
The source app is provenance. It is not identity.
## The first useful move [#the-first-useful-move]
Create one profile only for a real recurring role.
For example:
* name: `Cindy`
* id: `cindy`
* default space: `product`
* role: "Review product-facing changes. Be concise. Check tests before approving."
Then start that worker with `NMEM_AGENT_ID=cindy`, or pass `agent_id="cindy"` through a supported MCP or API call. The next Context Bundle should show Cindy as the selected AI profile.
## What an AI Profile can carry [#what-an-ai-profile-can-carry]
An AI Profile can define:
* a display name and stable id
* a short description of the agent's role
* a default space for memory reads and writes
* profile-specific Rules
* optional external aliases, used only when an integration needs to map its own stable worker id to a Mem profile
Keep it small. A profile should answer "who is working?" and "where should they usually work?", not contain every instruction the agent may ever need.
## How it differs from nearby concepts [#how-it-differs-from-nearby-concepts]
| Concept | Use it for |
| ---------------- | --------------------------------------------------------- |
| **Your Profile** | Who you are, your language, aliases, and personal context |
| **AI Profile** | Who this long-running agent is |
| **Space** | Which lane of memory this work belongs to |
| **Rule** | What behavior should always apply |
| **Skill** | How to perform one repeatable task |
If the same agent should behave differently for a different job, create a new profile. Do not overload one identity with incompatible work just because the host makes it easy to reuse a name.
## How connected tools select it [#how-connected-tools-select-it]
Mem selects an AI Profile only from an explicit identity signal.
For normal setups, use one of these:
* `NMEM_AGENT_ID`
* `agent_id`
Advanced integrations may also map their own stable worker id onto a profile:
* `NMEM_HOST_AGENT_ID`
* `host_agent_id`
Treat this as an external alias, not a second identity. Most users should never need it.
It does not select a profile from `source_app`. A plain Codex session should not become Cindy just because the source app is `codex`.
## What to ignore for now [#what-to-ignore-for-now]
You do not need a profile for every chat window. The default profile is fine for normal use.
You do not need to create profiles for every tool you use. Create profiles for stable roles, not for runtimes.
You do not need to design a full team hierarchy. Start with one real agent that comes back often.
## Where to go next [#where-to-go-next]
* [Context](/docs/ai-context) to preview what a selected profile receives.
* [Rules](/docs/concepts/rules) to shape behavior for everyone, one profile, or one space.
* [Spaces](/docs/spaces) if profiles need separate memory lanes.
# Background intelligence (/docs/concepts/background-intelligence)
Most of what makes Mem useful happens in the background. Entity extraction, EVOLVES detection, contradiction flagging, Crystal synthesis, Working Memory updates: these run without you doing anything. You save a memory or import a thread, and the system takes it from there.
This page explains what runs, when it runs, and what keeps it from going off the rails.
## Two kinds of triggers [#two-kinds-of-triggers]
Background tasks fall into two categories based on what starts them.
### Scheduled tasks [#scheduled-tasks]
These run on a clock, regardless of what you did today.
* **Daily briefing** runs early morning. Reviews recent activity, generates insights, flags contradictions, and writes a fresh Working Memory briefing for each active space. The Default space keeps the familiar `~/ai-now/memory.md` compatibility file.
* **Crystallization review** runs weekly. Looks for clusters of related memories that could be synthesized into a Crystal.
* **Insight detection** runs weekly. Searches for cross-domain connections and patterns across your knowledge base.
* **Skill suggestions** run every 3 days by default. Looks for repeated ways of working that may be worth teaching your AI as a [Skill](/docs/concepts/skills).
* **Rule suggestions** run every 3 days by default. Looks for repeated preferences and standing rules your agents may need to follow. Suggestions stay as drafts until you review them.
* **Memory compaction** runs weekly when enabled. Reviews redundant memories and consolidates confirmed duplicates.
* **Label consolidation** runs weekly when enabled. Reviews duplicate labels, including labels written in different languages, before merging them.
* **Community detection** runs periodically. Rebuilds the entity graph's community structure for community-based search.
* **Memory freshness** runs daily when enabled. Recalculates freshness and confidence scores for all memories.
* **Memory type review** runs every 3 days by default in small batches. Helps file memories as facts, decisions, procedures, learnings, or events so agents can retrieve the right context.
### Event-driven tasks [#event-driven-tasks]
These fire in response to something you did, after a short delay.
* **EVOLVES detection** is triggered when you save a new memory. The system checks whether it replaces, enriches, confirms, or challenges something you already know. See [knowledge evolution](/docs/concepts/evolves).
* **Entity extraction** is triggered alongside EVOLVES detection. Extracts entities and relationships for the knowledge graph.
* **Memory type review** is triggered in a small batch after new memories arrive. It improves how memories are organized without rewriting your saved memory text.
* **Working Memory refresh** is triggered when new memories arrive. Updates the current space's Working Memory so connected agents see new context quickly.
* **Cluster evaluation** is triggered after EVOLVES edges are created. Checks whether a new cluster has reached the threshold for Crystal formation.
## The cascade [#the-cascade]
These are not independent. A single action can trigger a chain:
You save a memory → EVOLVES detection runs → finds a "confirms" link to an older memory → cluster evaluation fires → discovers three related memories now form a strong enough cluster → a Crystal is created.
Each step in the cascade has its own delay, so the system batches work rather than reacting to every individual event instantly. If you save five memories in quick succession, the system processes them together rather than running five separate analysis passes.
## Guardrails [#guardrails]
Background intelligence burns LLM tokens. Without limits, a burst of activity could drain your token budget or produce low-quality results from rushing through too many tasks. Four layers prevent this.
**Debouncing.** Event-driven tasks wait before executing. If another event of the same type arrives during the wait, the timer resets. This batches rapid-fire events (like importing a conversation with many messages) into a single analysis pass.
**Hourly pacing.** When you keep a local hourly token limit, Mem also spaces out background LLM tasks so a busy backlog does not rush through the hour. Set the hourly limit to `0` or leave it blank to remove this local hourly pacing. Provider cooldowns, daily limits, and per-task safety checks still apply.
**Token budget.** You can set hourly and daily token limits. When the budget runs out, the system pauses LLM tasks until the next period. Direct-function tasks (like decay refresh and community detection) are not affected because they do not use LLM calls.
**Quality gates.** The system suppresses low-value output. If a daily briefing produces zero insights, zero Crystals, and zero flags, it stays silent rather than generating a "nothing to report" card. Insight detection checks against the last two weeks of previous insights to avoid duplicates. Crystal formation requires three or more converging sources before creating anything.
## Context injection [#context-injection]
Each background task receives pre-computed context before it starts. The daily briefing, for instance, gets a digest of the past week's activity, yesterday's Working Memory, graph statistics, and recent resolution patterns. This avoids expensive LLM discovery steps and keeps each task focused.
Context is capped to prevent prompt bloat. If the pre-computed context exceeds the cap, lower-priority sections are trimmed first.
## Working Memory [#working-memory]
Working Memory is the daily briefing's most visible output. Every morning, the system archives yesterday's working memory and writes a fresh one based on recent activity.
The Default space keeps a file at `~/ai-now/memory.md`. If you use spaces, other spaces get their own Working Memory briefings behind the same Mem APIs and integrations. This is how Claude Code, Grok Build, Cursor, Codex, and other tools know what you have been working on and what decisions you have made recently.
Working Memory also updates during the day. When you save new memories, the system refreshes the file (after a longer delay than other event-driven tasks, since it is more expensive to run). You can also edit it manually.
## Processing settings [#processing-settings]
The Processing settings page gives you two controls for most tasks:
* **Run** starts that task once now.
* **The switch** controls whether Mem may run that task automatically in the future.
Small maintenance runs from Settings apply their safe, reviewed changes. For example, Memory Type Review only applies high-confidence type fixes from a bounded batch.
The green dot in Settings means a background task is currently running. Open **Settings → Processing** to see the current task name, when it started, and any available progress.
Recent runs show the latest task outcomes and reported or estimated token usage. Non-LLM housekeeping tasks show `0 tokens`; LLM-backed tasks show approximate usage, and mark provider calls whose exact usage was not reported.
## Usage boundaries [#usage-boundaries]
The AI usage card in **Settings → Processing** is a local safety ledger, not a universal bill.
It tracks:
* automatic Mem background jobs that run on this device
* built-in foreground AI sessions such as AI Now and Graph Intelligence, when the provider reports usage
* Plus managed-AI credit, when you are signed in to a Plus plan
It does not track every AI call made around Mem. Browser or Exchange agents, browser extensions, external IDE agents, and third-party hosts may call models through their own runtime or provider account. Those costs can be real, but they belong to that host's own bill or provider dashboard, not this local Mem ledger.
If you use your own API key, the provider's dashboard is still the source of truth for billing. Mem's local numbers help you cap automatic work and notice unusual activity, but they are not a replacement for the provider invoice.
Some providers do not return token usage for every response. When that happens, Mem marks the run as partially reported so you know the total may be lower than the real spend.
Not every task has the same risk profile:
* **Safe housekeeping**: Memory Freshness and Memory Type Review improve which memories surface first and how they are filed. They do not rewrite your saved memory text.
* **Review-first maintenance**: Memory Maintenance can prepare a Timeline review when old or overlapping memories may be adding noise. The refresh itself never archives, merges, deletes, or rewrites memories.
* **Merging tasks**: Memory Compaction and Label Consolidation can merge graph records after review. They are off by default; turn them on only if you want Mem to keep those graphs tidier automatically.
* **Moving aside**: Low-risk facts and events can be moved out of everyday recall only after review. Preferences, decisions, procedures, plans, learnings, rules, identities, and context memories are not mechanically archived; they are treated as material for semantic organization instead.
For normal use, leave Background Intelligence on and keep the defaults. If you run a server or VPS install, use the token limits on the same page to cap background AI cost.
Large maintenance sweeps, such as full memory-type reclassification, can use substantial AI credit and touch many memories. Run them from the CLI, preview the result first, then apply it only when you understand the changes:
```bash
nmem memories reclassify-types --target-type procedure --full-scan --wait
nmem memories reclassify-types --target-type procedure --full-scan --apply --wait
```
## Task controls [#task-controls]
Every background task has its own toggle. You can turn off EVOLVES detection while keeping the daily briefing, or disable insight detection while keeping entity extraction. The master toggle disables everything at once.
Token budgets and scheduling (briefing hour, community detection interval) are also configurable. Background Intelligence requires a remote LLM to be configured, since the tasks run on your machine and need a model to reason with.
## Next steps [#next-steps]
* [Memory decay](/docs/concepts/memory-decay) covers the decay refresh task and how scores are calculated
* [Knowledge evolution](/docs/concepts/evolves) explains EVOLVES detection in detail
* [Crystals](/docs/concepts/crystals) explains crystallization review and what triggers Crystal creation
# Crystals (/docs/concepts/crystals)
You mention React performance tips in a ChatGPT session. A week later, you discuss the same topic in Cursor. A month after that, you save an article about it. Each memory is useful on its own, but none gives you the full picture.
Crystals are what happens when the system notices this convergence and synthesizes a single, comprehensive reference from the pieces.
## What a Crystal is [#what-a-crystal-is]
A Crystal is a memory, but a special kind. It is synthesized from three or more source memories that independently touch the same topic. The system reads the sources, identifies what each one contributes, and writes a unified summary that stands on its own.
The result is a reference article you can read without hunting down the original conversations. It answers the question "what do I actually know about X?" with a single, coherent document instead of scattered fragments.
Crystals are not auto-generated summaries. They require convergence from multiple independent sources, and the synthesis is evaluated for quality before anything is created.
## How Crystals form [#how-crystals-form]
Crystal formation follows a pipeline:
1. **EVOLVES detection** finds that a new memory relates to existing ones. The system creates relationship edges (replaces, enriches, confirms, or challenges).
2. **Cluster evaluation** fires after new edges are created. It checks whether any cluster of related memories has reached the convergence threshold: three or more source memories on the same topic, with enough distinct information to warrant synthesis.
3. **Synthesis** happens if the cluster qualifies. The system reads all source memories, identifies what each one contributes, and produces a unified Crystal. The Crystal links back to every source through CRYSTALLIZED\_FROM edges, so you can always trace where the knowledge came from.
This pipeline runs as part of [background intelligence](/docs/concepts/background-intelligence). A dedicated weekly crystallization review also scans for clusters that event-driven detection might have missed.
## Why three sources [#why-three-sources]
Two sources is a correlation. Three is a pattern. The minimum of three independent sources is a quality gate that prevents weak connections from being elevated to reference status.
The sources do not need to come from the same platform. A Crystal built from a ChatGPT conversation, a Cursor session, and a manually saved note is often more valuable than one built from three messages in the same thread, because the cross-platform convergence is stronger evidence that the knowledge matters.
## Reviewing Crystals [#reviewing-crystals]
Every Crystal starts as unreviewed. You can confirm it, dismiss it, or edit it.
**Confirm** means you have read the synthesis and it reflects your actual understanding. Confirmed Crystals receive a search ranking boost, so they surface more readily when you search. An amber banner on unreviewed Crystals shows Confirm and Dismiss buttons; once confirmed, a green check replaces it.
**Dismiss** means the synthesis missed the mark. Dismissed Crystals receive a heavy ranking penalty and are visually dimmed in your library. They are not deleted, so you can revisit the decision later.
**Edit** a Crystal's title or content and it is automatically confirmed. If the system got the gist right but the wording wrong, just fix it.
Crystals you have not reviewed yet receive no ranking boost. They need to earn trust before the system treats them as authoritative.
## Speaker attribution [#speaker-attribution]
When a Crystal draws from conversations between you and an AI assistant, the synthesis distinguishes who said what. Your own statements ("I will go with Postgres") are recorded as decisions. AI recommendations ("Based on your latency requirements, consider Redis") are recorded as suggestions with their reasoning.
This prevents the common problem where AI-recommended options are presented as if you chose them. Exploring an idea in conversation is not the same as committing to it.
## How Crystals affect search [#how-crystals-affect-search]
Confirmed Crystals receive a ranking boost in search results. The reasoning is straightforward: a confirmed Crystal represents corroborated, user-verified knowledge, which is more likely to be what you are looking for than any single raw memory.
The boost is meaningful but not overwhelming. A Crystal that is only loosely relevant to your query will not outrank a raw memory that is a perfect semantic match. Semantic relevance is still the dominant ranking signal. Unreviewed Crystals get no boost; dismissed Crystals are penalized.
Crystals also contribute to the [confidence score](/docs/concepts/memory-decay) of their source memories. If a memory has been used as a source for one or more Crystals, that counts as evidence of its value.
## What you see [#what-you-see]
Crystals appear in your feed timeline with their source count and the platforms they drew from. You can confirm, dismiss, or edit a Crystal directly from the feed without opening a separate view. Hover over a Crystal card and click the pencil icon to edit its title and content in place, then press Cmd+Enter to save. You can also open a Crystal to read the full synthesis and drill into individual sources for original context.
In the graph view, Crystals appear as distinct nodes with edges pointing back to their sources. Double-clicking a Crystal expands these edges so you can see the full provenance.
## Updates, not auto-mutation [#updates-not-auto-mutation]
Knowledge evolves. The sources that formed a Crystal might get updated, contradicted, or replaced by newer understanding. When this happens, the system flags the Crystal as stale and proposes a re-evaluation rather than silently rewriting it.
Crystals you have already confirmed are prioritized for re-evaluation. Crystals you dismissed are left alone. The system proposes; you decide.
## Next steps [#next-steps]
* [Knowledge evolution](/docs/concepts/evolves) explains the EVOLVES edges that feed into Crystal formation
* [Background intelligence](/docs/concepts/background-intelligence) covers when crystallization runs and how it is scheduled
* [Search architecture](/docs/concepts/search-architecture) explains how Crystals affect ranking
# Knowledge evolution (/docs/concepts/evolves)
Knowledge changes. You make a decision in March, refine it in June, and reverse it in October. Most systems either overwrite the old version or keep everything as a flat list. Neither is useful when you need to understand how your thinking evolved.
Nowledge Mem uses a model called EVOLVES to link related memories with explicit relationships. Instead of losing history or drowning in duplicates, you get a traceable chain of how each piece of knowledge transformed.
## Four relationship types [#four-relationship-types]
When the system detects that a new memory relates to an existing one, it creates one of four links:
| Relationship | What it means | When it happens |
| -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Replaces** | Your understanding has changed. The new memory supersedes the old one. | "Use CockroachDB" replaces "Use PostgreSQL" |
| **Enriches** | You added depth or detail to something you already knew. | "React 19 adds a compiler" enriches "React 18 introduced concurrent rendering" |
| **Confirms** | A separate source independently agrees with an existing memory. | Two separate code reviews both recommend the same library |
| **Challenges** | New information contradicts what you recorded before. | Your March assessment disagrees with your October conclusion |
These four types cover the ways knowledge actually moves: it gets updated, extended, validated, or contradicted.
## What this means in practice [#what-this-means-in-practice]
When you search for a topic, EVOLVES chains appear alongside individual results. You see not just the latest version, but the full trail of how you got there.
This is especially useful for decisions. Searching "database choice" does not just return the most recent decision. It returns the chain: original choice, the enrichment that added reasoning, the challenge that raised concerns, and the replacement that settled it.
### Version tracking without version control [#version-tracking-without-version-control]
EVOLVES links separate two kinds of relationships:
* **Progression** (`replaces`, `enriches`): these form a version chain. The system marks older replaced versions as superseded so everyday search returns the latest understanding. History views and CLI history search can still show the older versions.
* **Validation** (`confirms`, `challenges`): these are evidence, not versions. Confirming or challenging a memory does not replace it. Both the original and the new information stay active.
Labels propagate through progression chains automatically. If you label a memory "architecture" and a later memory replaces it, the new one inherits the label.
## How detection works [#how-detection-works]
When Background Intelligence is enabled, the system checks new memories against your existing knowledge. If semantic similarity is high enough, it evaluates the relationship type and creates the appropriate link.
This runs automatically as a background task, typically within a minute of saving a new memory. You can also see and manage EVOLVES links directly from any memory's detail view.
## When contradictions appear [#when-contradictions-appear]
Contradictions (the `challenges` relationship) are surfaced, not auto-resolved. The system shows both memories side by side and lets you decide: keep the new one, keep both, or dismiss the challenge.
This is a deliberate design choice. Automated conflict resolution would require the system to judge which version of your knowledge is "right." That judgment belongs to you.
## Next steps [#next-steps]
* [Background Intelligence](/docs/concepts/background-intelligence) explains when EVOLVES detection runs and what other tasks use it
* [Crystals](/docs/concepts/crystals) explains what happens when multiple EVOLVES chains converge
* [Search architecture](/docs/concepts/search-architecture) covers how EVOLVES chains affect search ranking
# How it works (/docs/concepts)
This section explains what happens under the hood when you use Nowledge Mem. It is written for users who want to understand *why* the system behaves the way it does, not just *how* to use it.
You do not need to read these pages to use Mem effectively. Everything here runs automatically. But if you have ever wondered why certain memories rank higher in search, how the system detects contradictions, or what happens while you sleep, this is where to look.
## What is covered [#what-is-covered]
* [LLM Wiki](/docs/concepts/llm-wiki) frames why the Library reads as a wiki, what the system does on its own, and what stays in your hands. This is the entry point if you want the model behind v0.8.
* [Open Knowledge Format (OKF)](/docs/concepts/open-knowledge-format) covers how you export your whole graph as an open, vendor-neutral markdown bundle any tool or agent can read.
* [Knowledge evolution](/docs/concepts/evolves) explains how memories transform over time. When you refine a decision or learn something that contradicts earlier thinking, the system tracks the relationship instead of overwriting history.
* [Memory Links](/docs/concepts/memory-links) explain how to connect two memories inside a space when they should be read together, even when the relationship is not version history or an entity link.
* [AI Profiles](/docs/concepts/ai-profiles) explain how Mem keeps long-running agents distinct from the tool that happens to run them.
* [Rules](/docs/concepts/rules) explain always-on behavior rules, how they differ from Skills and Memories, and how they reach connected agents.
* [Search architecture](/docs/concepts/search-architecture) describes how search combines multiple perspectives (semantic meaning, keywords, entity linking, community clusters, labels, and graph traversal) to find what you need.
* [Memory decay](/docs/concepts/memory-decay) covers how the system decides what to surface first. Recent and frequently used knowledge ranks higher. Important knowledge never disappears.
* [Memory lifecycle](/docs/concepts/memory-lifecycle) explains the three states a memory can be in (active, archived, removed) and why the count you see on the Memories page can differ from your graph or storage size without anything being lost.
* [Background intelligence](/docs/concepts/background-intelligence) walks through the daily pipeline: what runs, when, and what safeguards keep it from wasting resources or generating noise.
* [Skills](/docs/concepts/skills) explains how the system turns a repeated way of working into a procedure your AI can follow, and how a Skill earns trust before it is treated as proven.
* [Crystals](/docs/concepts/crystals) explains how the system synthesizes stable reference knowledge when multiple independent sources converge on the same insight.
## Where to start [#where-to-start]
If you are trying to understand why a specific search result appeared (or did not appear), start with [search architecture](/docs/concepts/search-architecture) and [memory decay](/docs/concepts/memory-decay).
If you want to understand the background features (briefings, contradictions, entity extraction), start with [background intelligence](/docs/concepts/background-intelligence).
If you are setting up several agents, start with [AI Profiles](/docs/concepts/ai-profiles), [Rules](/docs/concepts/rules), and [Context](/docs/ai-context).
# LLM Wiki (/docs/concepts/llm-wiki)
The Library now reads as a wiki, not a file pile. The wiki you are reading is the same knowledge Mem has been collecting in the background; the difference is that you can finally read it page by page, click through the connections, and ask a single concept the question you actually had.
Andrej Karpathy [described the underlying pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) very clearly: many small markdown pages, each focused on one entity or one topic, cross-linked with `[[wikilinks]]`, with an `index.md` as a directory. The LLM does the bookkeeping; you curate. Mem implements that idea on top of your knowledge graph.
## First useful action [#first-useful-action]
1. Open the Library and switch to the **Wiki** tab.
2. Pick a topic that already has memories under it. Read its summary, click into one of the listed entities, then click into a related entity.
3. From an entity, crystal, or topic page, click **Investigate**. The Knowledge Graph opens with that node (or the whole cluster) already selected.
You should be able to navigate three or four pages without typing once. That is the first signal that the wiki is yours to read.
## What Mem does for you [#what-mem-does-for-you]
The bookkeeping side of a personal wiki is exactly what kills most attempts at one. Mem treats it as the system's job, not yours.
* **Topic clustering.** Background Intelligence groups your knowledge into topics and gives each topic a name. The Wiki tab is the index for those topics. The first time you open it on a fresh install, run **Wiki Topic Detection** once from the Knowledge Graph view to fill the index; after that it refreshes automatically every 6 days, and you can change the cadence in *Settings · Processing · Advanced*.
* **Entity pages, derived live.** Each entity has a wiki entry built from the graph: where it sits in your topics, when it was first seen, the agent's confidence in it, aliases it picked up, the memories that mention it, the entities sitting next to it. There is no second copy you have to maintain.
* **Crystals as reference articles.** When three or more memories converge on the same idea, Mem synthesises a [Crystal](/docs/concepts/crystals): a stable reference page with `[[Entity]]` wikilinks already woven in. Every Crystal lists the source memories it was built from.
* **Evolution and contradictions.** [EVOLVES](/docs/concepts/evolves) edges track when newer knowledge replaces or refines older knowledge. Crystal pages show the older memories they grew out of and the newer ones they grew into.
* **Last-touched and recent activity.** Each topic page carries a "Recent on this topic" rail, so the wiki reflects what you have actually been thinking about lately.
## What you stay in charge of [#what-you-stay-in-charge-of]
The wiki is built around a clear division: Mem handles the bookkeeping, you handle the thinking.
* **Picking sources.** Drop in the document, conversation, or note. The wiki only grows from what you decide is worth feeding it.
* **Asking the questions.** The Knowledge Graph Agent and the Library's "Study with AI" both wait for you to point at something. They do not wander.
* **Deciding what to keep.** "Study with AI" proposes memories and Crystals; you tap **Save 1**, **Save all**, or **Skip**. Nothing auto-saves.
## The wiki sits on top of the writing path [#the-wiki-sits-on-top-of-the-writing-path]
Mem already had a writing path in place: ingest, parse, classify, extract entities, detect EVOLVES edges, synthesise Crystals, cluster into communities, all happening in the background as you use the tool. The Wiki tab is a *reading path* layered on top, not a new datastore.
That has a few useful consequences:
* **Pages are derived, not stored.** Edits happen at the data layer (memories, sources, crystals), and the wiki page refreshes from there. There is no parallel copy to drift out of sync.
* **Export is a snapshot, not a sync target.** [Wiki Export](/docs/library#wiki-export) gives you a one-shot folder of markdown files. Choose the Obsidian-style markdown wiki with `[[wikilinks]]`, or an [OKF bundle](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the same content in Google's open, vendor-neutral [Open Knowledge Format](/docs/concepts/open-knowledge-format), which formalizes this exact LLM Wiki pattern so other tools can read it. Re-export when you want a fresh copy. Editing the export does not flow back into Mem.
* **Investigate keeps you on the same canvas.** When you click Investigate, you stay in Knowledge Graph overview mode, the cluster is highlighted, and Graph Intelligence Agent reads the same selection you do. Anything the agent saves comes back to the topic page in Library.
## Where to go next [#where-to-go-next]
* [Library](/docs/library): the day-to-day surface where you read the wiki and run "Study with AI".
* [Crystals](/docs/concepts/crystals): how stable reference pages get synthesised.
* [Background Intelligence](/docs/concepts/background-intelligence): the work that keeps your wiki current without you asking.
* [EVOLVES](/docs/concepts/evolves): how Mem tracks the way your understanding moves.
# Memory decay (/docs/concepts/memory-decay)
You remember yesterday's meeting better than last month's. You recall a fact you use every day more easily than one you read once. Human memory works this way because it has to. Infinite recall with no prioritization would be as useless as forgetting everything.
Nowledge Mem applies a similar idea. Every memory carries two independent scores that influence where it appears in search results. One fades with time. The other only grows.
## Two scores, two jobs [#two-scores-two-jobs]
**Decay score** reflects freshness. A memory you saved today scores higher than one you saved six months ago, all else equal. The score drops over time following an exponential curve, with a frequency boost for memories you keep coming back to. If you access a memory regularly, the decay score stays high.
**Confidence score** reflects how well-supported a memory is. It starts at a baseline and increases as evidence accumulates. Confidence never decreases. A memory that has been accessed many times, linked through EVOLVES chains, or used as a source for a Crystal will have higher confidence than an isolated, untouched memory.
The two scores are independent. A memory can be old (low decay) but well-supported (high confidence), or recent (high decay) but unvalidated (low confidence). Both signals feed into the final search ranking alongside semantic relevance.
## What feeds into each score [#what-feeds-into-each-score]
### Decay score [#decay-score]
Two components, blended:
* **Recency**: exponential decay from the last time you interacted with the memory. Recent memories score higher. The curve has a half-life measured in weeks, not hours, so memories do not vanish overnight.
* **Frequency**: a logarithmic function of how many times the memory has been accessed. Frequent use keeps a memory fresh even if the last access was not today.
Recency carries more weight than frequency. A memory you used heavily last year but have not touched since will still fade, just more slowly than one you never accessed.
### Confidence score [#confidence-score]
Six signals, each capped so no single signal can dominate:
1. **Access frequency**: how often the memory has been retrieved
2. **Search appearances**: how often it shows up in search results
3. **Explicit clicks**: how often you open and read it
4. **Reading time**: how long you spend on it when you do open it
5. **EVOLVES edges**: how many other memories confirm or enrich it
6. **Crystal membership**: whether it has been used as a source for a Crystal
These signals are tracked automatically. You do not need to rate or tag memories for the system to learn which ones matter.
## The importance floor [#the-importance-floor]
Decay creates a problem: a genuinely important fact that you do not access for months will score low, even though it is still correct and valuable. Spaced repetition systems solve this by scheduling reviews. Mem is not a flashcard app.
Instead, each memory has an importance floor. The decay score can drop, but it will never fall below a minimum threshold tied to the memory's importance level. A foundational decision or a critical procedure stays retrievable even if you have not looked at it in a long time.
The floor is modest. It does not override semantic relevance. It just prevents "ghost memories": knowledge that exists in your system but effectively cannot be found.
## How decay affects search ranking [#how-decay-affects-search-ranking]
Semantic relevance is the dominant factor in search results. Decay and confidence are secondary signals that adjust the ordering when semantic scores are close.
In practice:
* Two memories equally relevant to your query → the fresher one ranks higher
* A semantically strong match always beats a recent but weakly relevant one
* A well-supported memory (high confidence) gets a small additional boost
* Crystals and latest versions in EVOLVES chains get their own ranking adjustments on top of this
## Automatic refresh [#automatic-refresh]
The system recalculates decay and confidence scores daily as a background task. This refresh also updates the cached scores used in search, so results reflect current usage patterns without any manual intervention.
The refresh itself never archives, deletes, merges, or rewrites memories. It keeps ranking signals current.
Memory growth is handled separately by **Memory Maintenance**. When Mem sees pressure from stale or overlapping memories, it can prepare a review in the Timeline. From there, you can move low-risk facts and events out of everyday recall, queue semantic organization for richer memories, or keep everything as-is.
*A Memory Health review shows the current batch, recent coverage, and the remaining backlog before you choose what to tidy.*
This distinction matters:
* Facts and events can be low-risk cleanup candidates when they are old, unvisited, and not protected.
* Preferences, decisions, plans, procedures, learnings, rules, identities, and context memories are never mechanically archived by freshness alone.
* Moving something out of everyday recall is reversible. Forgetting or deletion is always an explicit action.
## Next steps [#next-steps]
* [Search architecture](/docs/concepts/search-architecture) explains how decay and confidence feed into the full ranking pipeline
* [Knowledge evolution](/docs/concepts/evolves) covers EVOLVES chains, which contribute to confidence scores
* [Crystals](/docs/concepts/crystals) explains Crystal membership, another confidence signal
# Memory lifecycle (/docs/concepts/memory-lifecycle)
Nothing you save is silently thrown away. That is the one thing to hold onto while reading this page.
A memory can be in everyday use, quietly kept in the background, or genuinely gone. The only way something reaches that last state is because you asked for it. Everything else is still there, still yours, still searchable.
## The three states [#the-three-states]
**Active** is what your everyday recall sees. When you search, when your AI answers a question, when the Memories page lists what you know, it is drawing from active memories. This is the working set: the version of your knowledge you are actually using right now.
**Archived** is kept but out of the way. A memory becomes archived when a newer version replaced it, or when you retired or paused it because it was no longer current. It has not gone anywhere. You can still find it through history views and history search. It just no longer competes for attention in everyday recall, so the latest understanding surfaces first.
**Removed** is the only state that means gone. A memory reaches it when you delete or forget it, on purpose. It leaves everywhere at once. Nothing moves a memory here on its own.
A helpful way to hold this:
> **Stored** = Active + Archived. That is everything you still have.
## Why you may see different numbers [#why-you-may-see-different-numbers]
You will sometimes notice that the count on the Memories page does not match the number implied by your graph or storage size. This is expected, and it is not a sign that anything went missing. Each view is a different lens on the same knowledge.
* The **Memories page** and the **Stats headline** show your **active** memories: the working set you recall from every day.
* The **graph** and your **storage size** count everything **stored**: active plus archived history. Older replaced versions still take up space and still live in the graph, so this number is larger.
* **Crystals** (the synthesized summaries Mem writes when several sources agree) are counted on their own, separate from your memory count.
Same knowledge, three lenses. A lower active number is not a loss. It usually just means some older versions moved into archived history, which is exactly what keeps everyday recall focused on what is current.
## What moves something between states [#what-moves-something-between-states]
Most transitions happen for a clear reason:
* When you refine or replace a piece of knowledge, the earlier version becomes archived history rather than being overwritten. See [Knowledge evolution](/docs/concepts/evolves) for how these version chains work.
* When a memory grows stale, Mem may prepare a review so you can move low-risk facts out of everyday recall. Freshness and decay only affect *ranking*, never deletion. See [Memory decay](/docs/concepts/memory-decay).
* Retiring, forgetting, and deleting are always explicit actions you take. Moving something out of everyday recall is reversible. Deletion is the one thing that is not.
## Next steps [#next-steps]
* [Memory decay](/docs/concepts/memory-decay) explains how freshness affects search ranking without ever removing anything.
* [Knowledge evolution](/docs/concepts/evolves) explains how superseded versions become archived history you can still trace.
# Memory Links (/docs/concepts/memory-links)
A Memory Link is for one plain action: telling Mem that two memories should be read together.
Use it when one memory changes how another should be understood. A launch plan may depend on an earlier pricing assumption. A migration note may be the risk behind an implementation plan. A real example may be the missing context that makes a rule usable.
This is different from search similarity. Search can guess that two memories look related. A Memory Link is something you, or an agent working with clear intent, decided to keep.
## Try it once [#try-it-once]
1. Open **Graph** from the sidebar.
2. Select a Memory node.
3. Choose **Connect memories**.
4. Select another Memory in the same Space.
5. Type a short relation name, or use a suggestion.
6. Add a reason if the connection is not obvious, then save.
The two memories must be in the same Space. That keeps work, projects, clients, and agent teams from being linked by accident.
## How to know it worked [#how-to-know-it-worked]
You should see a line between the two Memory nodes. Select that line to inspect the relation name and reason.
Later, when an agent or graph tool reads one of those memories, the link gives it a stronger clue than "these two texts are similar." It can bring the other memory nearby and know why it matters.
## Good relation names [#good-relation-names]
You do not need a perfect taxonomy. Start with the words you would use in your own work:
| Relation | Use it when |
| ------------- | ------------------------------------------------------------- |
| `supports` | one memory is evidence for another |
| `contradicts` | one memory conflicts with another, but is not a newer version |
| `depends_on` | one memory needs another to make sense |
| `example_of` | one memory is a concrete example of a rule or pattern |
| `blocks` | one memory blocks a plan or action |
| `same_topic` | both memories cover the same subject and are useful together |
You can also type your own names, such as `migration_risk_for`, `pricing_assumption_for`, or `source_of_truth_for`. Mem normalizes names, so `same topic`, `same-topic`, and `same_topic` are treated as the same relation.
## How this differs from other links [#how-this-differs-from-other-links]
| Use this | When you mean |
| ---------------- | -------------------------------------------------------------------------------------- |
| **Memory Link** | These two specific memories should be read together for this reason |
| **EVOLVES** | This memory updates, replaces, enriches, confirms, or challenges an older version |
| **Label** | Many memories belong in the same broad group |
| **Entity graph** | A memory mentions people, projects, tools, concepts, or extracted entity relationships |
| **Search** | Find memories that look relevant, even when no relationship has been saved |
If the connection is really a newer version of old knowledge, use the EVOLVES relationship instead. If you only want a broad bucket, use a label.
## What to ignore for now [#what-to-ignore-for-now]
You do not need to design a full relation system before using Memory Links. Name the relationship that is useful today.
You do not need to use AI suggestion. It can draft a relation name and reason, but it only fills the form. You still decide what to save.
You do not need to think about APIs or MCP tools unless you are building an integration. The Graph view is the normal starting point.
## For agents and integrations [#for-agents-and-integrations]
Supported integrations can read and write Memory Links through the REST API and MCP tools:
* `memory_relation_add`
* `memory_relation_suggest`
* `memory_relation_list`
* `memory_relation_update`
* `memory_relation_delete`
The graph stores these as one stable memory-to-memory edge with an open relation name. That keeps the schema small while still letting your vocabulary grow over time.
## Where to go next [#where-to-go-next]
* [Knowledge Graph](/docs/knowledge-graph) if you want to create or inspect Memory Links visually.
* [Knowledge evolution](/docs/concepts/evolves) if you want to understand version history and contradictions.
# Open Knowledge Format (OKF) (/docs/concepts/open-knowledge-format)
Nowledge Mem can export your whole knowledge graph as an **Open Knowledge Format (OKF)** bundle: an open, vendor-neutral way to represent knowledge as plain markdown files with YAML frontmatter. Nothing proprietary sits between you and your knowledge, and any tool that reads OKF can read your export.
OKF was published by Google Cloud's Knowledge Catalog team. It formalizes the [LLM Wiki](/docs/concepts/llm-wiki) pattern Mem was already built on, so speaking it was a natural fit.
## Export an OKF bundle [#export-an-okf-bundle]
1. Open the **Library** and switch to the **Wiki** tab.
2. Click **Download** on the tab row.
3. Choose **OKF bundle**.
You get a `.zip` containing an `index.md`, a `log.md`, and your knowledge laid out as directories: your memories grouped by type (`memories/decision/`, `memories/procedure/`, and the rest), plus `crystals/`, `entities/`, `topics/`, `artifacts/`, `skills/`, and a `labels/` catalog. Every page carries YAML frontmatter, concepts link to each other with standard markdown paths, and the bundle is conformant with the OKF reference tools.
*The OKF export is the portable version of your Library Wiki: markdown files, frontmatter, and standard links.*
For the full export flow and the second format, see [Library: Wiki Export](/docs/library#wiki-export).
## Why it is useful [#why-it-is-useful]
* **Portable.** A bundle is just markdown files. Open it in any editor, render it on GitHub, or version-control it next to your code.
* **Vendor-neutral.** Any OKF reader, including the reference tools Google ships, can open it. You are not locked into one app's format.
* **Human- and agent-readable.** The same file works for a person skimming it and an AI agent parsing it, with no translation layer in between.
## OKF bundle vs Markdown wiki [#okf-bundle-vs-markdown-wiki]
The Library export offers two formats, and both cover your whole graph. The OKF bundle uses standard markdown links and the spec's frontmatter, so it is the interoperable choice. The **Markdown wiki** keeps the `[[wikilinks]]` you see inside Mem, so it drops straight into Obsidian or Logseq. Pick OKF for an interoperable copy; pick the markdown wiki for an Obsidian-style vault.
Both are a snapshot, not a sync target: edits you make outside Mem do not flow back. Re-export whenever you want a fresh copy.
## Where to go next [#where-to-go-next]
* [Library](/docs/library): the day-to-day surface where you export.
* [LLM Wiki](/docs/concepts/llm-wiki): the reading model OKF formalizes.
* [Back up, export, and import](/docs/data-portability): the separate full-data backup and migration path.
* [Read the OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md): the canonical spec from Google Cloud.
* [How Nowledge Mem came to speak OKF](https://nowledge-labs.ai/blog/open-knowledge-format): the announcement.
# Rules (/docs/concepts/rules)
A Rule is an always-on behavior instruction for your connected agents.
Use Rules for things that should shape behavior before search, tools, or task-specific skills begin. They are the centralized version of the small instructions many power users already keep in `AGENTS.md`, `CLAUDE.md`, Cursor rules, Codex profiles, or a Hermes soul.
## What belongs in a Rule [#what-belongs-in-a-rule]
A good Rule changes how an agent behaves across many tasks:
* "Answer concisely unless I ask for detail."
* "Do not edit generated API docs by hand."
* "For release work, check tests before saying the change is ready."
* "When writing Chinese docs, write natural Chinese instead of translating English line by line."
Rules are not for everything. If the instruction is a repeatable task method, make it a [Skill](/docs/concepts/skills). If it is something you learned, save it as a Memory. If it only matters today, keep it in Working Memory.
## The first useful move [#the-first-useful-move]
Open **Context → Rules** and add one rule you keep repeating to agents.
Choose the narrowest useful scope:
| Scope | Use it when |
| ------------------ | --------------------------------------------- |
| **Everyone** | Every connected AI should follow it |
| **One AI Profile** | Only a named agent should follow it |
| **One Space** | It only applies inside a project or team lane |
Then open **Context → Preview**. You should see the rule in the startup context for the matching agent.
## Rules, Skills, and Memories [#rules-skills-and-memories]
These three can look similar, but they do different jobs:
| Thing | What it means |
| ---------- | ------------------------------------------- |
| **Rule** | "Always behave this way." |
| **Skill** | "When doing this task, follow this method." |
| **Memory** | "This is something worth remembering." |
Example:
* Rule: "Do not hand-edit generated OpenAPI docs."
* Skill: "How to add a new API endpoint without breaking generated docs."
* Memory: "The OpenAPI docs are generated from Python docstrings."
The boundary matters because Rules are injected early and often. A vague or wrong Rule can steer many sessions. Keep Rules short, specific, and easy to inspect.
## Suggested Rules [#suggested-rules]
Mem can suggest candidate Rules when repeated behavior shows up in your work. A suggestion is not automatically applied. You can accept it, edit it, or ignore it.
This keeps the useful part of automation, noticing repeated preferences and project habits, without letting the system silently rewrite how your agents behave.
## How connected tools consume Rules [#how-connected-tools-consume-rules]
Supported connectors read Rules through the Context Bundle at session start. The bundle combines your profile, the selected AI Profile, active space, Rules, Working Memory, and useful file-system paths.
Some older or simpler integrations may only read Working Memory. In that case, Rules still help inside Mem and in newer connectors, but the older tool may not see them until its integration is updated.
## What to ignore for now [#what-to-ignore-for-now]
You do not need to turn every preference into a Rule. If you would not want it repeated in most future sessions, do not make it always-on.
You do not need to write long policy documents. Short rules are easier for agents to follow and easier for you to trust.
You do not need to understand MCP or KFS paths to use Rules. Start in the Context view.
## Where to go next [#where-to-go-next]
* [AI Profiles](/docs/concepts/ai-profiles) if different agents need different behavior.
* [Skills](/docs/concepts/skills) if the behavior is really a task method.
* [Context](/docs/ai-context) to preview the final startup bundle.
# Search architecture (/docs/concepts/search-architecture)
Searching personal knowledge is different from searching the web. You are looking for things you saved yourself, in your own words, sometimes months ago. The biggest challenge is not speed. It is the gap between how you phrase a question now and how you phrased the answer then.
Nowledge Mem addresses this by searching from multiple angles at once, then blending the results.
## Six search strategies [#six-search-strategies]
Every search query runs through up to six parallel strategies:
**Semantic search.** Compares the meaning of your query against the meaning of each memory using vector embeddings. "API authentication" finds "JWT token setup" even though the words are different. This is the primary signal for most queries.
**Full-text search.** Keyword matching with language-aware tokenization, including CJK (Chinese, Japanese, Korean) support. Useful when you remember exact terms, names, or code identifiers.
**Entity search.** Uses the knowledge graph to find memories linked to relevant entities. Searching "database performance" can surface a memory about "PostgreSQL indexing" through their shared entity connections, even if the memory text never mentions "database performance."
**Community search.** The knowledge graph groups related entities into communities (clusters of strongly connected nodes). Searching within a community surfaces memories you might not find through direct keyword or semantic matching.
**Label search.** If your query matches a label you have assigned, memories with that label get a relevance boost. This lets your own organizational structure influence search results.
**Graph traversal.** Follows relationship edges (EVOLVES chains, entity links, Crystal sources) to find memories connected to your query through the graph structure rather than text similarity.
## Fast mode and deep mode [#fast-mode-and-deep-mode]
Not every search needs all six strategies at full power.
**Fast mode** (under 100ms for most queries) runs semantic search, full-text search, and entity matching in parallel. It handles about 90% of queries well. This is the default.
**Deep mode** adds LLM-powered analysis on top of the fast results. It classifies your query intent (are you looking up a fact? exploring a concept? tracing a relationship?) and adjusts strategy weights accordingly. It can also use HyDE (hypothetical document embeddings) to bridge large expression gaps, and optionally re-evaluate top results with an LLM for better ranking.
Deep mode is triggered automatically for queries that include temporal intent ("what did I decide last quarter?"), or when fast mode results are low-confidence. You can also trigger it manually.
## How results are ranked [#how-results-are-ranked]
The final ranking blends signals from the strategies above with memory-level scoring:
* **Semantic relevance** is the dominant factor. A memory that is semantically close to your query will rank high regardless of other signals.
* **Decay score** gives a modest boost to recently and frequently accessed memories. See [memory decay](/docs/concepts/memory-decay) for details.
* **Confidence score** provides a small additional boost to memories with strong evidence (many accesses, EVOLVES links, Crystal citations).
Crystals (synthesized reference knowledge) receive a ranking boost because they represent corroborated, high-confidence knowledge. Current memories in EVOLVES chains are returned by default; superseded memories stay in graph history and can be included when you explicitly ask for history.
Every result includes a `source_thread_id` when available. If an agent or tool needs more context beyond the memory itself, it can pull the original conversation.
## Temporal search [#temporal-search]
Queries with time references ("what happened in 2020?", "decisions from last quarter") activate temporal matching. The system tracks two independent timestamps for each memory:
* **Event time**: when the thing happened
* **Record time**: when you saved it
Temporal matching adds a relevance boost but does not override semantic relevance. A memory from the right time period still needs to be semantically relevant to rank well. Time is a signal, not a filter.
Date precision is tracked explicitly. If a memory's event time is known only to the year, the system will not pretend to know the month.
## Next steps [#next-steps]
* [Memory decay](/docs/concepts/memory-decay) explains the decay and confidence scores that influence ranking
* [Knowledge evolution](/docs/concepts/evolves) covers how EVOLVES chains affect what appears in results
* [Search & Relevance](/docs/search-relevance) is the reference page with practical search tips
# Skills (/docs/concepts/skills)
You figure out the right order to cut a release: commit the submodules first, then move the parent pointer. You get it wrong once, learn the lesson, and from then on you just do it. It lives in your head, not in any document.
A Skill is what happens when Mem captures that way of working and hands it to your AI as a procedure it can follow later.
## What a Skill is [#what-a-skill-is]
A Skill is a repeatable way of performing a task, written down so an agent can do it the way you would. The useful ones are small and specific: an order of operations, a safety check, a release gotcha, a review habit, a debugging move.
It is not a saved prompt, and it is not a standing rule. A standing rule ("keep answers short") belongs in [Context](/docs/ai-context) as a Rule. A Skill is the *how* of a task, the step a capable stand-in would get wrong without your experience.
Skills are also not auto-generated checklists. A good model can already write a plausible-looking process. The point of a Skill is to carry the part that only came from your real work, the thing that is not obvious until you have done it. Every Skill traces back to the work that earned it, and every Skill stays off until you turn it on.
## How a Skill is born [#how-a-skill-is-born]
There are three ways a Skill comes to exist, and all three flow into the same lifecycle.
1. **Suggested.** As part of [background intelligence](/docs/concepts/background-intelligence), Mem looks for repeated ways of working in your memories and threads. When the same procedure shows up across separate occasions, it proposes a Skill, with the source moments attached as evidence. This is why a memory filed as a `procedure` matters: typed procedures are what the suggestion pass reads first. See [knowledge evolution](/docs/concepts/evolves) for how memories get their type.
2. **From scratch.** You can author a Skill directly by describing what you want. Mem asks one question, drafts the procedure, and shows it back to you to review. You can bring in your own threads, sources, or notes as material.
3. **Imported.** If you already keep skill files for an agent host (a `SKILL.md` and its bundle), you can enroll them. The body is kept verbatim and then flows into the same draft, verify, and improve loop as everything else.
However it starts, a Skill compiles into a small bundle: the procedure itself as a `SKILL.md`, plus any optional scripts, references, and evaluation cases. It is compiled, not merely stored, so the version your AI reads is consistent no matter where the Skill came from.
## What the trust badge tells you [#what-the-trust-badge-tells-you]
Once a Skill is on, your agent follows it for real, so before you turn one on you want to know it actually works. Every Skill shows a trust badge so you can tell at a glance how far it has been tested:
* **Checked** means it passed one test. It works, but on a single example.
* **Proven** means it passed two or more, so you can count on it across different situations.
Mem runs these tests for you, using examples drawn from the same work the Skill came from, so you do not have to set anything up. When you open a Skill, the badge is the quick answer to "can I rely on this yet?"
## How your AI uses a Skill [#how-your-ai-uses-a-skill]
A Skill is only useful if the agents you already work with can read it. When you turn a Skill on, Mem materializes it as real files and registers it with your connected hosts through each host's native mechanism, for example `~/.claude/skills` for Claude Code, or the equivalent location for Codex and other agents. The format is the universal `SKILL.md` convention, so one Skill works across hosts. Some tools reach Mem over a live connection rather than a skills folder; there the agent finds the Skill through Mem when a task calls for one, instead of loading it from disk.
The agent then reads the Skill the same way it reads any of its own skills. One agent learning it means the rest can use it. The host is just the runtime; the Skill, and the trust behind it, stays with you.
Turning a Skill off keeps it but stops materializing it, which is different from removing it. Both are reversible.
## Sharpening a Skill [#sharpening-a-skill]
You can ask Mem to sharpen a Skill over time. When you do, it tries a revision and tests it against the version you already have, using examples drawn from the Skill's own evidence.
It only keeps the change if the new version tests better. If nothing beats what you have, it keeps nothing and tells you so. Sharpening can improve a Skill, but it will not quietly swap in something worse, so it is always safe to ask.
## How Skills relate to the rest of Mem [#how-skills-relate-to-the-rest-of-mem]
Skills sit alongside the other things Mem keeps, each with a different job:
* A **Memory** is something you know. A **Skill** is something your AI can do. A memory typed as a `procedure` is the most common raw material for a Skill.
* A **[Crystal](/docs/concepts/crystals)** synthesizes stable reference knowledge when several sources converge. A Skill is closer in spirit, also compiled rather than raw, but it produces an executable procedure instead of a reference article.
* A **Rule** in [Context](/docs/ai-context) shapes how an agent behaves in general. A Skill shapes how it performs one specific task.
## What you see [#what-you-see]
Skills live in the **Skills** view. The home shows your active Skills and any suggestions waiting for you, each suggestion carrying the evidence from your own work that prompted it. Opening a Skill shows the procedure as the main content, its trust state, and where it came from. Turning one on, off, or removing it is always your call.
## Next steps [#next-steps]
* [Background intelligence](/docs/concepts/background-intelligence) covers when skill suggestions run and the budget that governs them
* [Knowledge evolution](/docs/concepts/evolves) explains how memories get the `procedure` type that suggestions read first
* [Context](/docs/ai-context) is where standing rules live, the behavior layer that sits next to Skills
* If you script against Mem, the [Skills API reference](/docs/api/skills/get) lists the REST endpoints
# Alma (/docs/integrations/alma)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Alma. If you use Alma Skills, enable the bundled nowledge-mem Skill or copy it to ~/.config/alma/skills/nowledge-mem. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Memory that follows every Alma conversation. Install once from the marketplace, then optionally enable the bundled Alma Skill so Alma knows when to use memory tools more deliberately. Connect to a remote Mem instance with Access Anywhere for use across machines.
Source: [community/nowledge-mem-alma-plugin](https://github.com/nowledge-co/community/tree/main/nowledge-mem-alma-plugin)
Install the plugin, open a fresh Alma thread, and ask Alma: "Use the Nowledge Mem status tool and tell me whether the server is connected." The `nowledge_mem_status` result should report `ok: true` and `serverConnected: true`. If your Mem library already has memories, ask a follow-up that depends on past work. On a brand-new library, status plus thread capture is enough.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Alma installed, with access to its plugin marketplace
## Setup [#setup]
### Install from the Alma Plugin Marketplace [#install-from-the-alma-plugin-marketplace-step]
In Alma, open **Settings** → **Plugins** → **Marketplace**, search for **Nowledge Mem**, and click **Install**.
### Restart Alma if prompted [#restart-alma-if-prompted-step]
### Optional: enable the Alma Skill [#optional-enable-the-alma-skill-step]
The plugin works without this step: tools, auto-recall, and thread sync are handled by the plugin. If you use Alma's **Settings → Skills** page, look for the bundled `nowledge-mem` Skill and enable it if it appears. It teaches Alma when to read Context Bundle, search prior work, inspect source threads, and save durable decisions.
If the Skill does not appear after installing the plugin, copy it into Alma's personal skills folder and refresh Skills:
```bash
mkdir -p ~/.config/alma/skills/nowledge-mem
cp ~/.config/alma/plugins/nowledge-mem/skills/nowledge-mem/SKILL.md \
~/.config/alma/skills/nowledge-mem/SKILL.md
```
### Verify in a fresh thread [#verify-in-a-fresh-thread-step]
Ask Alma to run the status tool:
```text
Use the Nowledge Mem status tool and tell me whether the server is connected.
```
Then send one short normal message and wait a few seconds, switch threads, or quit Alma cleanly. The conversation should appear in Nowledge Mem under **Threads** with source `alma`.
## Update [#update]
Open **Settings** → **Plugins** → **Marketplace** in Alma, find Nowledge Mem, and click **Update** if a newer version is available.
## Disable or Uninstall [#disable-or-uninstall]
* To pause automatic thread capture without uninstalling, set `autoCapture` to off in the Nowledge Mem plugin settings.
* To pause preloaded recall, set `recallPolicy` to `off` or use `strict_tools` when you only want explicit tool calls.
* To remove the integration, disable or uninstall Nowledge Mem from Alma's **Settings → Plugins** page. If you installed a local copy manually, quit Alma and remove `~/.config/alma/plugins/nowledge-mem`.
## Customize Safely [#customize-safely]
Alma does not expose a separate package-owned override file for this plugin.
* Use Alma's plugin settings for durable behavior changes such as remote mode, recall policy, thread capture, and space selection
* If you want the agent to speak or save differently, use Alma's Skills, prompts, or instruction surfaces instead of patching plugin code
Do not edit installed plugin files just to keep a small preference. For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## What the Plugin Does [#what-the-plugin-does]
| Feature | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Auto-recall** | Injects Working Memory + relevant memories on the first message of every thread |
| **13 tools** | Memory: query, search, store, show, update, delete. Threads: search, show, create, delete. Plus Context Bundle, Working Memory, and status diagnostics |
| **Access Anywhere** | Connect to a remote Mem instance via API URL + API key in plugin settings |
| **Live settings** | Change API URL, API key, recall policy, or auto-capture. Takes effect immediately, no restart |
| **Status diagnostics** | `nowledge_mem_status` shows connection mode, server health, CLI availability, and current config |
| **Live thread sync** | Saves conversations after a few seconds of idle, on thread switch, and on quit (on by default) |
| **Native Alma Skill** | Optional `nowledge-mem` Skill for better tool-selection guidance in Alma's Skills surface |
| **Local-first** | Uses the Nowledge Mem API on this machine. No cloud required unless you enable Access Anywhere |
## Thread Saving [#thread-saving]
Threads are saved automatically during normal use: the plugin syncs your conversation after a few seconds of idle, when you switch threads, or when you quit Alma. No action needed. Saved threads appear in the Nowledge Mem desktop app and can be distilled into structured memories later.
During conversation, the AI may also save specific insights or decisions as individual memories using the `nowledge_mem_store` tool. This happens when the conversation produces something durable, such as architecture decisions, debugging conclusions, preferences. For casual chat, the AI intentionally avoids saving noise.
If you want something specific remembered, just ask: "save this to memory."
## Full-library backup (optional) [#full-library-backup-optional]
For a **portable archive** of every Alma thread, whether for a new Mem library, compliance, or a clean machine, use Alma **Settings → Data → Export all threads**. That produces `alma-backup-*.zip` with `threads.json` inside.
In Nowledge Mem, open **Threads → Import → Bulk Import** and pick the ZIP. Imported threads use the same `alma` source label as live plugin sync, so filters stay consistent. Other bulk formats and CLI options: [Import existing conversations](/docs/import-existing-conversations) and [Bulk import formats](/docs/threads#bulk-import).
## Access Anywhere [#access-anywhere]
To connect to a remote Nowledge Mem instance:
1. In Alma, open **Settings** → **Plugins** → **Nowledge Mem**
2. Set **API URL** to your remote server (e.g. `https://mem.example.com`)
3. Set **API Key** to your `nmem_...` key
4. Changes take effect immediately. Use `nowledge_mem_status` to verify
The API key is read from Alma's plugin settings, sent as an `Authorization: Bearer ...` header, and never logged.
## Spaces [#spaces]
Alma can keep one ambient memory lane per profile.
* Use `NMEM_SPACE="Research Agent"` when you already launch Alma in one stable lane.
* Or set `nowledgeMem.space` in Alma settings when one Alma profile always belongs to one lane.
* `nowledgeMem.spaceTemplate` is only for advanced setups where your launcher already exports a trustworthy lane variable, such as `${ALMA_AGENT_NAME}`.
If Alma does not know a real agent identity, stay on **Default** or use separate Alma profiles for separate lanes.
## Related [#related]
* [Connectors overview](/docs/integrations): native connectors, reusable packages, MCP, and browser capture
* [Claude Code](/docs/integrations/claude-code) · [Claude Desktop](/docs/integrations/claude-desktop) · [Codex](/docs/integrations/codex-cli) · [OpenClaw](/docs/integrations/openclaw) · [Raycast](/docs/integrations/raycast) · [Others](/docs/integrations/other-chat-ai)
# Antigravity CLI (/docs/integrations/antigravity-cli)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Antigravity CLI. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Google has replaced Gemini CLI with **Antigravity CLI** (`agy`). Gemini CLI stopped serving individual-tier accounts (Google AI Pro, Ultra, and free Code Assist) on **June 18, 2026**. Antigravity CLI shares the same agent harness as the Antigravity desktop platform and reuses your existing `~/.gemini` home directory, so most Gemini CLI setups carry over.
Antigravity CLI is Google's official successor to Gemini CLI. The migration story is good: it reads the same `~/.gemini` home, honors both `GEMINI.md` and `AGENTS.md`, and can import installed Gemini CLI extensions as Antigravity plugins — including the Nowledge Mem extension.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Antigravity CLI installed:
```bash
# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Windows (PowerShell)
irm https://antigravity.google/cli/install.ps1 | iex
```
* `nmem` in your `PATH` (see [installation](/docs/installation) or use the desktop app's **Settings → Preferences → Developer Tools → Install CLI**)
On first launch, `agy` signs you in with your Google account and offers to import your existing Gemini CLI configuration (MCP servers, allow-listed commands, keybindings, theme). Accepting that prompt is the fastest starting point.
## One-Minute Setup [#one-minute-setup]
### Install Nowledge Mem for Gemini CLI first [#install-nowledge-mem-for-gemini-cli-first-step]
If you have not already, install the Nowledge Mem extension for Gemini CLI — see [Gemini CLI](/docs/integrations/gemini-cli). The Antigravity path builds on top of it.
### Import the extension into Antigravity [#import-the-extension-into-antigravity-step]
```bash
agy plugin import gemini
```
This converts installed Gemini CLI extensions — including Nowledge Mem — into Antigravity plugins.
### Run `nmem status` once [#run-nmem-status-once-step]
For the default same-machine setup, this should point to `http://127.0.0.1:14242 (default)`.
### Open a new `agy` session [#open-a-new-agy-session-step]
The imported plugin loads its context files, commands, and bundled MCP tools automatically, the same way it did under Gemini CLI.
## MCP Configuration [#mcp-configuration]
Antigravity CLI keeps MCP servers in a dedicated `mcp_config.json` (workspace path: `.agents/mcp_config.json`). If you configure the Mem MCP server manually, note one format difference: remote server definitions use `serverUrl` instead of `url`.
Generate the right block for your setup:
```bash
nmem config mcp show --host gemini-cli
```
Then place it in `.agents/mcp_config.json`, renaming `url` to `serverUrl` for remote servers. This keeps Antigravity's MCP tools and `nmem` pointed at the same Mem server.
## Import Older Sessions [#import-older-sessions]
Session capture uses the same local history under `~/.gemini`, so the existing Gemini CLI import path applies:
```bash
# Preview
nmem t sync --from gemini-cli --all-projects --limit 20
# Import
nmem t sync --from gemini-cli --all-projects --apply
```
Use `-p /path/to/project` when you only want one project.
## Customize Safely [#customize-safely]
Both context files work in Antigravity CLI:
* project `GEMINI.md` or `AGENTS.md`
* optional `~/.gemini/GEMINI.md` for personal defaults
Do not edit the installed plugin files directly. Full map: [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Your First Success State [#your-first-success-state]
You know Antigravity CLI is wired correctly when:
* `agy plugin import gemini` completes and the Nowledge Mem plugin appears in a new session
* `nmem status` returns successfully
* Context Bundle or Working Memory appears at the start of a fresh session when there is context to show
* `save-thread` imports a real session, and long sessions are saved before compression as well as at session end
## Known Boundaries [#known-boundaries]
* The import path (`agy plugin import gemini`) is Google's official migration channel and the supported way to run the Nowledge Mem extension under Antigravity today.
* Session capture currently reads the shared `~/.gemini` history through the Gemini CLI connector. If Google moves Antigravity session storage, capture behavior may change; check `nmem t sync --from gemini-cli --limit 5` after upgrading `agy`.
## Related [#related]
* [Gemini CLI](/docs/integrations/gemini-cli)
* [Connectors overview](/docs/integrations)
* [Remote access](/docs/remote-access)
# Browser Extension (/docs/integrations/browser-extension)
Nowledge Mem Exchange captures memories and thread backups from supported web AI chat platforms. It runs beside your conversations in Chrome, Edge, Arc, and Firefox using the browser's native side panel or sidebar.
Open one supported chat, open the side panel, then do exactly one thing: auto-capture one useful insight, manually distill one conversation, or back up one thread. When that result appears in Mem, the extension path is working.
Firefox uses its native sidebar. The same capture, Manual Distill, and Thread Backup workflows work there. Browse Now browser control is separate and still requires Chrome, Edge, Arc, or another Chromium browser.
## Smart Distill [#smart-distill]
The extension now treats a conversation as something it can inspect intelligently, not just export blindly. Auto-Capture and Manual Distill both read the live thread selectively, check what already exists in Mem, and then decide whether to create or update memories.
## Three Ways to Capture [#three-ways-to-capture]
| Mode | How it works | When to use |
| ------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Auto-Capture** | Monitors your conversations and autonomously saves valuable insights | Set it and forget it. The extension decides what's worth remembering |
| **Manual Distill** | You trigger capture on a conversation you want to save | When you know a conversation contains something important |
| **Thread Backup** | Imports the full conversation as a thread, with incremental dedup | Archive entire conversations for later distillation in the app |
## Auto-Capture [#auto-capture]
When enabled, the extension watches the live conversation and applies a high bar before saving anything:
* **Refined conclusions**: decisions, plans, finalized approaches
* **Important discoveries**: breakthroughs, key findings
* **Knowledge explorations**: deep dives, research synthesis
Routine Q\&A and generic exchanges are skipped. Before saving, the extension can inspect the thread more closely, check for duplicates in Mem, and update an existing memory instead of creating a redundant one.
If Auto-Capture does save something, it first makes sure the conversation is backed up as a canonical thread in Mem. That way the memory keeps a reliable link back to the real conversation it came from.
## Manual Distill [#manual-distill]
Manual Distill is for the moments when you know a conversation matters and want Mem to do a careful pass.
Instead of compressing the whole thread into one quick summary, the extension now:
* reads the live conversation selectively
* looks for motivations, constraints, decisions, and reusable context
* checks what is already in Mem
* can create or update multiple memories from one conversation when that is the better result
This makes Manual Distill much better for long working sessions, design discussions, debugging threads, and conversations where the most reusable part is in the middle rather than the last answer.
Auto-capture requires a configured LLM provider. Open the SidePanel, go to **Settings**, and add your API key. Supported providers: OpenAI, Anthropic, Google, xAI, OpenRouter, Ollama, and OpenAI-compatible endpoints.
## Thread Backup [#thread-backup]
Imports the full conversation as a thread. Subsequent backups only capture new messages (incremental sync). You can still back up a thread explicitly whenever you want a full archive.
The extension also backs up the canonical thread automatically when it writes new browser-derived memories, so those memories keep strong provenance without requiring you to back up every conversation manually.
For local coding assistants, Nowledge Mem also supports native connector capture plus **AI Conversation Discovery** for older local sessions from **Claude Code, Cursor, Codex, and OpenCode**. See [Threads](/docs/threads#auto-sync) for details.
## Supported Platforms [#supported-platforms]
The extension works with the supported web AI chat platforms below:
| Platform | Sites |
| --------------------- | -------------------------- |
| **ChatGPT** | openai.com, chatgpt.com |
| **Claude** | claude.ai |
| **Gemini** | gemini.google.com |
| **NotebookLM** | notebooklm.google.com |
| **Microsoft Copilot** | copilot.microsoft.com |
| **Perplexity** | perplexity.ai |
| **DeepSeek** | chat.deepseek.com |
| **Kimi** | kimi.moonshot.cn |
| **Qwen** | qwen.ai, tongyi.aliyun.com |
| **POE** | poe.com |
| **Manus** | manus.im |
| **Grok** | grok.com, grok.x.ai, x.ai |
| **Open WebUI** | localhost, private IPs |
| **ChatGLM** | chatglm.cn |
| **MiniMax** | agent.minimaxi.com |
The browser extension captures from ChatGPT into Mem. If you want ChatGPT itself to search Mem during a conversation, use [ChatGPT Web and Desktop](/docs/integrations/chatgpt-web) and connect Remote MCP over OAuth.
Paid users with a configured LLM can auto-generate handlers for any AI chat site. Navigate to the site, open the SidePanel, and click **Generate handler**. The extension analyzes the page structure and creates a custom handler automatically.
## Connect Extension to Access Mem Anywhere [#connect-extension-to-access-mem-anywhere]
If your Mem API is exposed through **Settings → Access Mem Anywhere** in the desktop app:
1. Open any supported AI chat page, then open the extension SidePanel
2. Click **Settings**
3. Set **Fixed Space** only if this browser profile should always stay in one named lane. Leave it empty to stay on `Default`.
4. In **Access Mem Anywhere**, paste:
* `export NMEM_API_URL="https://"`
* `export NMEM_API_KEY="nmem_..."`
5. Click **Fill URL + key**
6. Click **Save**, then **Test connection**
## Spaces [#spaces]
The browser extension is a fixed-lane surface.
* Leave **Fixed Space** empty if this browser profile should keep using **Default**
* Set one named space if this browser profile always belongs to one lane, such as `Research Agent`
* Do not expect the extension to infer per-agent routing from the web page itself
When you do set a fixed space, the extension keeps memory search, memory writes, thread reads, source reads, and Working Memory reads in that same lane.
Full guide (Quick link and Cloudflare account modes): [Access Mem Anywhere](/docs/remote-access).
## Download [#download]
The extension also supports downloading any conversation thread as a `.md` file for archiving or sharing.
A complete example with all supported features
## Next Steps [#next-steps]
* **[Memories](/docs/memories)**: What the extension captures. Create, search, and organize your knowledge
* **[Threads](/docs/threads)**: Thread backup and distillation workflow
* **[Access Mem Anywhere](/docs/remote-access)**: Connect the extension to a remote Mem instance
# Bub × Nowledge Mem (/docs/integrations/bub)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Bub. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="One-liner install"
pip install nowledge-mem-bub
```
Bub records every session through its tape system. Nowledge Mem adds the layer above: knowledge from all your other AI tools, decisions made in Claude Code, preferences set in Cursor, insights from ChatGPT, searchable inside Bub. And what you learn in Bub flows back to every other tool.
## Before You Start [#before-you-start]
* **Nowledge Mem** running locally ([installation](/docs/installation))
* **Bub** installed ([bub.build](https://bub.build))
* **`nmem` CLI** in your PATH: in Nowledge Mem go to **Settings → Preferences → Developer Tools → Install CLI**, or `pip install nmem-cli`
```bash
nmem status # Nowledge Mem is running
uv run bub --help # Bub is available
```
## Setup [#setup]
### Install the plugin [#install-the-plugin-step]
```bash
pip install nowledge-mem-bub
```
### Verify hooks [#verify-hooks-step]
```bash
uv run bub hooks
```
You should see `nowledge_mem` listed for `system_prompt`, `build_prompt`, and `save_state`.
### Try a knowledge-backed prompt [#try-a-knowledge-backed-prompt-step]
Ask Bub something that depends on your past work:
```bash
uv run bub run "what was I working on this week?"
```
If you have existing knowledge in Nowledge Mem, the agent should find it through `mem.search`. That's success: Bub can now see knowledge from your other tools.
## Update [#update]
```bash
python3 -m pip install --upgrade nowledge-mem-bub
```
## Customize Safely [#customize-safely]
Bub does not have a separate durable instruction file for this plugin today.
* Use environment variables and Bub's own runtime prompt/config surfaces for durable behavior changes
* Keep the installed Python package as shipped; do not patch site-packages just to change language, recall style, or save thresholds
For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## What You Can Do [#what-you-can-do]
**Find knowledge from other tools**
Ask "what did we decide about the database?" and the agent searches across decisions you made in Claude Code, insights from ChatGPT, notes from Cursor, not just this Bub session.
**Save knowledge for everywhere**
When you reach a conclusion in Bub, `mem.save` stores it so your next Claude Code session, Cursor project, or ChatGPT conversation can find it too.
**Start with today's context**
With session context mode on, your Working Memory briefing and relevant past knowledge are ready before you ask. No repeating yourself across tools.
**Trace how ideas evolved**
`mem.connections` shows how a decision changed over time, which tools you discussed it in, and what source documents back it up.
## Two Modes [#two-modes]
| Mode | Config | What happens |
| ------------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| **Default** | nothing | The agent searches and saves on demand. Conversations flow into Mem for other tools to find. |
| **Session context** | `NMEM_SESSION_CONTEXT=1` | Working Memory and relevant knowledge injected automatically each turn. |
Most users should start with the default. Enable session context when you want guaranteed recall from the first message.
## Tools [#tools]
| Tool | What it does |
| ----------------- | ------------------------------------------------------------------------- |
| `mem.search` | Search knowledge from all your tools. Supports label and date filters. |
| `mem.save` | Save a decision, insight, or preference so any tool can find it. |
| `mem.context` | Read today's Working Memory: focus areas, priorities, recent activity. |
| `mem.connections` | Explore how a piece of knowledge relates to others across tools and time. |
| `mem.timeline` | Recent activity grouped by day. |
| `mem.forget` | Delete a memory by ID. |
| `mem.threads` | Search past conversations from any tool. |
| `mem.thread` | Fetch full messages from a conversation with pagination. |
| `mem.status` | Connection and configuration diagnostics. |
All tools work as Bub comma commands too: `,mem.search query=...`
## Configuration [#configuration]
No config needed for local use.
| Env Variable | Default | What it does |
| ---------------------- | --------- | ------------------------------------------------------- |
| `NMEM_SESSION_CONTEXT` | `false` | Inject Working Memory + recalled knowledge each turn |
| `NMEM_SESSION_DIGEST` | `true` | Feed Bub conversations into Mem for other tools to find |
| `NMEM_API_URL` | *(local)* | Remote Nowledge Mem server URL |
| `NMEM_API_KEY` | *(none)* | API key for remote access |
For a persistent shared setup, configure this machine once with `nmem config client ...`. Environment variables still take priority when you need a temporary override.
### Spaces [#spaces]
Bub is process-scoped today.
* Use `NMEM_SPACE="Research Agent"` when one Bub process belongs to one lane.
* If you run several Bub agents with different memory lanes, give each process its own `NMEM_SPACE`.
* If you do not have a real lane, stay on **Default**.
### Remote access [#remote-access]
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
See [Access Mem Anywhere](/docs/remote-access).
## Troubleshooting [#troubleshooting]
**Plugin not loading.** Run `uv run bub hooks` and check for `nowledge_mem`. Make sure `nowledge-mem-bub` is installed in the same Python environment as Bub.
**nmem not found.** `pip install nmem-cli && nmem status`
**Server not responding.** Start the Nowledge Mem desktop app, or check `nmem status` for diagnostics.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code) · [OpenClaw](/docs/integrations/openclaw) · [Alma](/docs/integrations/alma) · [Gemini CLI](/docs/integrations/gemini-cli)
* Plugin source: [nowledge-mem-bub-plugin](https://github.com/nowledge-co/community/tree/main/nowledge-mem-bub-plugin)
* [tape.systems](https://tape.systems) · [bub.build](https://bub.build)
# ChatGPT Web and Desktop (/docs/integrations/chatgpt-web)
ChatGPT can work with Nowledge Mem in two different ways:
* **Browser extension**: capture insights and back up the current ChatGPT thread from the browser side panel.
* **Remote MCP over OAuth**: let ChatGPT call your Mem server as a connector, so ChatGPT Web and ChatGPT desktop can search memories, threads, and library context during a chat.
Use the browser extension when you want to save from ChatGPT. Use Remote MCP when you want ChatGPT to read from Mem.
## Option 1: Capture ChatGPT Conversations [#option-1-capture-chatgpt-conversations]
Install **Nowledge Mem Exchange** if you want Mem to capture decisions, discoveries, and full thread backups from the ChatGPT page you are using.
### Install the browser extension [#install-the-browser-extension-step]
Follow the [Browser Extension guide](/docs/integrations/browser-extension), then open the side panel on `chatgpt.com`.
### Choose what to save [#choose-what-to-save-step]
Use **Always Remember** for automatic high-signal memory capture, **Manual Distill** when you know a thread matters, and **Thread Backup** when you want the full conversation saved as a thread.
## ChatGPT Business and Team History [#chatgpt-business-and-team-history]
Personal ChatGPT accounts can usually use [OpenAI's official data export](https://help.openai.com/en/articles/7260999-how-do-i-export-my-chatgpt-history-and-data), then import the exported `chat.html` through [Import existing conversations](/docs/import-existing-conversations). ChatGPT Business, Enterprise, and some Team workspaces may not expose the same full conversation export in ChatGPT settings today.
If you need old workspace history in Mem, treat this as a data portability workflow:
* For conversations you can still open, use the Exchange side panel to save the current thread.
* For files you already exported locally, import them from **Threads → Import → Bulk Import** or with the local `nmem` CLI.
* For company or team data, check your workspace policy first. Do not paste ChatGPT access tokens into tools you do not fully trust.
Community threads discuss tools such as
[chatGPT\_extractor](https://github.com/richlow/chatGPT_extractor) and
[export-chatgpt](https://github.com/brianjlacy/export-chatgpt) for ChatGPT
Team or Business history. These are not OpenAI or Nowledge Mem tools. They may
depend on ChatGPT web session tokens or private endpoints, may break when
ChatGPT changes, and may be disallowed by your workspace policy. Use them only
for data you are allowed to export, on a machine and codebase you trust.
After you have a local export folder, you can ask your coding agent to do the import safely:
```text
I exported my ChatGPT Business/Team conversations to:
/path/to/export-folder
Please inspect the files locally without uploading them anywhere. Use the local
`nmem` CLI to import the conversations into Nowledge Mem as ChatGPT threads.
Start with a small sample, verify with `nmem t list --source chatgpt -n 5`,
then import the rest. Preserve titles and timestamps when available, set the
source to `chatgpt`, and do not create long-term memories automatically.
```
For a single Markdown, JSON, or HTML file, the agent can start with:
```bash
nmem t import --file /path/to/conversation.md --source chatgpt
```
For context on why this is needed, see the OpenAI community discussion about [ChatGPT Team export limitations](https://community.openai.com/t/export-chats-in-chatgpt-team/620984/29).
## Option 2: Let ChatGPT Use Mem Through MCP [#option-2-let-chatgpt-use-mem-through-mcp]
Use this when ChatGPT asks for a remote MCP connector URL. Mem uses Access Anywhere plus OAuth, so you do not paste a private `nmem_` API key into ChatGPT.
ChatGPT is a cloud client. It cannot reach `localhost` or a private LAN
address on your machine. Configure Access Anywhere with a public HTTPS
endpoint first, then copy the Mem MCP endpoint that ends with `/mcp`.
### Start Remote MCP OAuth in Mem [#start-remote-mcp-oauth-in-mem-step]
Open **Mem → Connectors → AI Tools → Remote MCP over OAuth**, then click **Start setup**.
You can do this from the desktop app, the desktop app in remote-client mode, or
the web client at your public HTTPS Mem address.
Mem opens a pairing page in your browser and copies the `/mcp` URL. Keep using
that same browser profile for the ChatGPT OAuth approval step.
If you accidentally close the pairing page or ChatGPT's approval page, return
to **Remote MCP over OAuth** in Mem and click **Start over**. Mem opens a fresh
pairing page immediately; you do not need to wait for the previous 30-minute
pairing window to expire.
If you are using the web client or a desktop app connected to a remote Mem
server, the OAuth setup is created on that remote server. The copied MCP URL
will use that server's public HTTPS address, not `127.0.0.1`.
### Create a connector in ChatGPT settings [#create-a-connector-in-chatgpt-settings-step]
Open [ChatGPT Connectors Advanced settings](https://chatgpt.com/#settings/Connectors/Advanced), then choose **Create**.
### Paste the Mem MCP endpoint [#paste-the-mem-mcp-endpoint-step]
Copy the **Access Anywhere MCP endpoint** from Mem. It must end with `/mcp`, for example:
```text
https://your-access-anywhere-domain.example/mcp
```
Paste that URL into ChatGPT and continue.
### Approve Mem through OAuth [#approve-mem-through-oauth-step]
When Mem opens the OAuth approval page, allow ChatGPT to use Mem. If you see
"Pair this browser with Mem", return to Mem, click **Start over**,
and continue in the same browser profile that opened the pairing page.
### Confirm the connector was created [#confirm-the-connector-was-created-step]
ChatGPT should now show the Mem connector in its connector list.
### Enable the connector in ChatGPT [#enable-the-connector-in-chatgpt-step]
Allow the connector for the current ChatGPT workspace or chat context.
### Ask ChatGPT to use Mem [#ask-chatgpt-to-use-mem-step]
Ask ChatGPT to search your Mem context. In ChatGPT Web or the ChatGPT desktop app, mention `@Nowledge Mem`, then ask for what you need, for example: "Search my Mem for the project decision about the database migration."
ChatGPT currently creates custom connectors from the web settings page. Once
the connector is added, the same ChatGPT account can use it in the ChatGPT
desktop app by mentioning `@Nowledge Mem` in a chat.
## Which Path Should I Use? [#which-path-should-i-use]
| Goal | Use |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Save useful ChatGPT conversations into Mem | Browser extension |
| Let ChatGPT Web or desktop search Mem during a conversation | Remote MCP over OAuth |
| Import years of old ChatGPT history | [Import existing conversations](/docs/import-existing-conversations) |
| Bring over ChatGPT Team or Business history without an official export | Export locally with a tool you trust, then import files with `nmem` |
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Access Anywhere](/docs/remote-access)
* [Browser Extension](/docs/integrations/browser-extension)
* [Import existing conversations](/docs/import-existing-conversations)
# Claude Code (/docs/integrations/claude-code)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Claude Code. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="One-liner install"
claude plugin marketplace add https://github.com/nowledge-co/community && claude plugin install nowledge-mem@nowledge-community
```
Claude Code supports plugins: install once for built-in autonomous behavior. No system prompts or MCP configuration needed.
Your agent searches what you know, saves what matters, without you asking.
Install the plugin, make sure `nmem` is available, start a new Claude Code session, and verify one real behavior: Context Bundle or Working Memory loads at session start, or `/search` / `/save` works without extra wiring.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Claude Code installed
## Setup [#setup]
### Install the plugin [#install-the-plugin-step]
```bash
# Add the Nowledge community marketplace
claude plugin marketplace add https://github.com/nowledge-co/community
# Install the Nowledge Mem plugin
claude plugin install nowledge-mem@nowledge-community
```
The plugin requires `nmem` CLI:
```bash
# Option 1 -- uvx (no installation needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from nmem-cli nmem --version
# Option 2 -- pip
pip install nmem-cli
```
> If the Nowledge Mem desktop app is on this machine, the safest path is **Settings → Preferences → Developer Tools → Install CLI**. For remote-only machines without the desktop app, use `uvx` or install manually.
### Use slash commands and skills [#use-slash-commands-and-skills-step]
**Slash commands:**
* `/save`: Save the current session to Nowledge Mem
* `/sum`: Distill insights from this conversation
* `/search `: Search your knowledge base
* `/status`: Check server connection and status
**Natural language:** Say "Save this session" or "Distill this conversation" and Claude runs the right `nmem` command automatically.
**Autonomous (skills):** The plugin includes three skills that run on their own:
* **Read Working Memory**: loads Context Bundle when available, or your daily briefing fallback at session start and after context compaction
* **Search Memory**: searches when you reference past work
* **Distill Memory**: suggests distillation at breakthrough moments
**On request:** **Save Thread**: saves sessions when you ask ("save this session", "checkpoint this")
## Update [#update]
```bash
claude plugin marketplace add https://github.com/nowledge-co/community
claude plugin marketplace update nowledge-community
claude plugin update nowledge-mem@nowledge-community
# Restart Claude Code to apply changes
```
## Import Older Sessions [#import-older-sessions]
Automatic capture starts after the plugin and hooks are installed. To bring older Claude Code sessions into Nowledge Mem, preview first:
```bash
nmem t sync --from claude-code --all-projects --limit 20
```
Then import:
```bash
nmem t sync --from claude-code --all-projects --apply
```
Use `-p /path/to/project` instead of `--all-projects` when you only want one project. The command reads local Claude Code session files on this machine and writes to the Mem server configured in `nmem`.
## Spaces [#spaces]
Spaces are optional and explicit. The Claude Code plugin does not create or select a Mem space from your current folder, git repository, branch, or project name. Without an override, Context Bundle, Working Memory, search, and automatic session capture all use your default Mem space.
Set `NMEM_SPACE` only when this whole Claude Code process should use an existing Mem space:
```bash
NMEM_SPACE="Research Agent" claude
```
For multi-agent launchers, prefer a stable `NMEM_AGENT_ID` for the worker identity. Add `NMEM_SPACE` only when that worker should override its identity's default space.
## Customize Safely [#customize-safely]
Use Claude Code's own memory files, not the installed plugin directory:
* `CLAUDE.local.md` for your personal tweaks that should survive updates
* `CLAUDE.md` for repo-shared rules
Do not edit the installed Nowledge Mem plugin files directly. For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Lifecycle Hooks [#lifecycle-hooks]
The plugin uses [Claude Code hooks](https://code.claude.com/docs/en/hooks) for automatic lifecycle management:
| Event | Trigger | Action |
| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
| `SessionStart` (startup/resume/clear) | New session, resume, or clear | Loads Context Bundle via `nmem context`, falls back to `nmem wm read`, then local file |
| `SessionStart` (compact) | After context compaction | Re-loads Context Bundle or Working Memory + prompts Claude to checkpoint progress |
| `UserPromptSubmit` | Every user message | Injects search/save syntax as context Claude can see |
| `PreCompact` | Before manual or automatic compaction | Saves the exact Claude Code session before context is compressed |
| `Stop` | Model finishes responding | Captures session to knowledge graph with a bounded retry window |
Context Bundle, or Working Memory on older CLIs, is refreshed after compaction. The `PreCompact` hook saves the full local transcript before Claude Code compresses it, and the `Stop` hook keeps normal turn-by-turn capture running even when Nowledge Mem runs on a different machine (remote mode). If Claude Code needs a moment to flush the transcript file after a response, the hook waits and retries instead of reporting a silent no-op save.
If the desktop app's Claude Code file watcher is also enabled, you can leave it on. The watcher and plugin hooks converge on the same `claude-code-` thread, so repeated saves update the existing thread instead of creating a second one.
### Local vs Remote [#local-vs-remote]
The plugin works transparently in both modes:
* **Local** (Mem on same machine): Context Bundle or Working Memory is read through Mem. The plugin keeps `~/ai-now/memory.md` only as the Default-space compatibility fallback when the API path is unavailable. Sessions are captured by the desktop app file watcher, the Stop hook, and the PreCompact hook before context compression.
* **Remote** (Mem on different machine): configure this machine once:
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
That writes the shared local client config used by `nmem` and the plugin. You can still use environment variables (`NMEM_API_URL`, `NMEM_API_KEY`) for temporary overrides. Priority: CLI flags > env vars > config file > defaults.
When the Stop or PreCompact hook runs `nmem t save --from claude-code`, Claude's session files are read locally on the machine running Claude Code, then uploaded to Mem as normalized thread messages. By default that means `~/.claude`, but if you've moved Claude's config, `CLAUDE_CONFIG_DIR` is used automatically. The remote Mem server does not need direct access to that local folder.
## Go Further [#go-further]
**[AGENTS.md](https://github.com/nowledge-co/community/blob/main/examples/AGENTS.md)**: a complete memory-keeper agent example using the [agents.md standard](https://agents.md/). Works with any AI coding agent.
## Related [#related]
* [Connectors overview](/docs/integrations): native connectors, reusable packages, MCP, and browser capture
* [Claude Desktop](/docs/integrations/claude-desktop) · [Codex](/docs/integrations/codex-cli) · [Alma](/docs/integrations/alma) · [OpenClaw](/docs/integrations/openclaw) · [Raycast](/docs/integrations/raycast) · [Other Chat AI](/docs/integrations/other-chat-ai)
# Claude Desktop (/docs/integrations/claude-desktop)
Install once on macOS or Windows. No separate Python or Node install is required. After that, Claude Desktop can search your memory, save new context, and update existing knowledge during any conversation.
After install, click the `+` button in Claude Desktop and open **Connectors**. You should see **Nowledge Mem** listed there, ready to use in chat.
## Before You Start [#before-you-start]
* Nowledge Mem is running on this machine ([installation](/docs/installation)), or you already have a reachable remote Mem server
* Claude Desktop is installed and up to date
## Setup [#setup]
### Download the extension [#download-the-extension-step]
### Install and restart Claude Desktop [#install-and-restart-claude-desktop-step]
Double-click the downloaded `claude-dxt.mcpb` file, click **Install**, then restart Claude Desktop once.
### Use Mem in chat [#use-mem-in-chat-step]
Ask Claude to save insights, search your memories, or update anything in your knowledge base.
## Access Mem Anywhere [#access-mem-anywhere]
The extension connects to your local Mem by default. For remote access, it reads the same shared client config as `nmem`.
If you're starting **Access Anywhere** from Nowledge Mem Desktop on the same machine, you usually do not need to do anything else. The desktop app writes this config for you automatically.
If Claude Desktop is running on a different machine, configure that machine first:
Recommended:
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
This writes the same shared client config that Claude Desktop reads. Manual file paths are below if you prefer to inspect or edit it directly.
Path:
```text
~/.nowledge-mem/config.json
```
Path:
```text
%USERPROFILE%\.nowledge-mem\config.json
```
Use your server root URL in `apiUrl`. If you already have an older config that ends in `/remote-api` or `/mcp`, the extension still accepts it.
Restart Claude Desktop after changing the connection.
## Troubleshooting [#troubleshooting]
If Mem does not appear in Claude Desktop:
1. Click the `+` button in the chat box and open **Connectors**. Confirm **Nowledge Mem** is listed.
2. Open **Settings → Extensions → Advanced Settings** in Claude Desktop and inspect the extension status and logs.
3. If you're using remote access, run `nmem config client show` and verify the URL and API key state are correct on that machine.
## Related [#related]
* [Connectors overview](/docs/integrations): native connectors, reusable packages, MCP, and browser capture
* [Claude Code](/docs/integrations/claude-code) · [Codex](/docs/integrations/codex-cli) · [Alma](/docs/integrations/alma) · [OpenClaw](/docs/integrations/openclaw) · [Raycast](/docs/integrations/raycast) · [Other Chat AI](/docs/integrations/other-chat-ai)
# CodeBuddy × Nowledge Mem (/docs/integrations/codebuddy)
Paste this into CodeBuddy:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for CodeBuddy. Verify with nmem status and the Context Bundle or Working Memory check, then run a short session and confirm the thread appears with nmem t list --source codebuddy.
```
CodeBuddy can use Nowledge Mem through a native CodeBuddy plugin. The plugin gives CodeBuddy startup context, Mem MCP tools, quick commands, and lifecycle hooks that sync CodeBuddy's local transcript into Mem Threads.
This guide is for **CodeBuddy Code**, the terminal coding agent. For Tencent's office-agent surface, use the [WorkBuddy guide](/docs/integrations/workbuddy); WorkBuddy uses the same plugin abstraction but stores configuration under `.workbuddy`.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* CodeBuddy Code is installed
* `nmem` works on the same machine as CodeBuddy
```bash
nmem status
codebuddy --version
```
If `nmem` exists but rejects `t sync --from codebuddy` or `config mcp show --host codebuddy`, update the CLI before debugging MCP or session sync:
* Desktop-bundled CLI: open Mem and run **Settings → Preferences → Developer Tools → Install bundled CLI** again.
* PyPI CLI: `python3 -m pip install --user --upgrade nmem-cli`
* pipx CLI: `pipx upgrade nmem-cli`
If CodeBuddy runs on a different machine from the Mem desktop app, install the standalone CLI there first and point it at your Mem server:
```bash
python3 -m pip install --user nmem-cli
nmem config client set url https://your-server
nmem config client set api-key your-key
```
## Install The Plugin [#install-the-plugin]
Add the Nowledge community marketplace, then install the plugin:
```text
/plugin marketplace add nowledge-co/community
/plugin install nowledge-mem@nowledge-community
```
The marketplace is backed by `community/.codebuddy-plugin/marketplace.json`. The plugin includes:
* a CodeBuddy plugin manifest
* a local MCP server for `http://127.0.0.1:14242/mcp/`
* startup guidance and a Nowledge Mem skill
* hooks for `Stop`, `SessionEnd`, `PreCompact`, and `SubagentStop`
* quick commands under `/nowledge-mem:*`
For remote Mem or authenticated localhost, generate a CodeBuddy MCP block:
```bash
nmem config mcp show --host codebuddy
```
Paste the generated `nowledge-mem` server into `~/.codebuddy/.mcp.json`, `$CODEBUDDY_CONFIG_DIR/.mcp.json`, or a project `.mcp.json`.
## Thread Sync [#thread-sync]
CodeBuddy passes `session_id` and `transcript_path` to lifecycle hooks. The Nowledge Mem plugin uses those fields instead of guessing where the latest transcript is.
After install, the hook runs:
```bash
nmem --json t sync --from codebuddy --session-id --session-dir --all-projects --apply
```
That command runs on the CodeBuddy machine, reads the local `.jsonl` transcript under `$CODEBUDDY_CONFIG_DIR/projects` or `~/.codebuddy/projects`, and uploads normalized messages to your local or remote Mem server. It is safe to rerun; Mem deduplicates repeated imports.
## Verify [#verify]
Start a new CodeBuddy session and ask:
```text
Is Nowledge Mem connected? Read my current context.
```
Success means CodeBuddy can call the Nowledge Mem MCP tools and return Context Bundle, Working Memory, or an empty-but-successful memory result.
Then finish a short exchange and check:
```bash
nmem t list --source codebuddy -n 5
```
You should see the recent CodeBuddy thread after the hook has run. If hooks do not appear to run, check:
```bash
tail -n 50 ~/.codebuddy/logs/nowledge-mem-hook.log
```
If you set `CODEBUDDY_CONFIG_DIR`, check that directory's `logs/nowledge-mem-hook.log` instead.
## Import Older Sessions [#import-older-sessions]
Preview first:
```bash
nmem t sync --from codebuddy --limit 20
```
Import when the preview looks right:
```bash
nmem t sync --from codebuddy --apply
```
For a custom CodeBuddy config directory:
```bash
CODEBUDDY_CONFIG_DIR="$HOME/.my-codebuddy-config" nmem t sync --from codebuddy --apply
```
## Customize Behavior [#customize-behavior]
Use CodeBuddy's own instruction surfaces:
* `~/.codebuddy/CODEBUDDY.md` for personal global guidance
* project `CODEBUDDY.md` for shared repo guidance
* `.codebuddy/rules/*.md` for structured project rules
Do not edit installed plugin files. Marketplace updates can replace them.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Threads](/docs/threads)
* CodeBuddy docs: [Plugin Reference](https://www.codebuddy.ai/docs/cli/plugins-reference) · [Hooks Reference](https://www.codebuddy.ai/docs/cli/hooks) · [MCP](https://www.codebuddy.ai/docs/cli/mcp)
# Codex (/docs/integrations/codex-cli)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Codex. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Best result on modern Codex: install the plugin, keep the bundled Nowledge Mem MCP server enabled, and run the hook setup once. SessionStart injects your current Nowledge context, prompt routing keeps historical work pointed at the cross-tool source, MCP gives Codex low-friction retrieval and write tools, and the Stop hook captures the real transcript.
Switch between Codex, Claude Code, Gemini, and Cursor without losing context. The Codex package injects Context Bundle / Working Memory at startup, bundles a local MCP server, routes continuation work toward search, and captures threads automatically. Codex still decides when a targeted search is useful, but it no longer has to choose Nowledge from skill descriptions alone. That is why the recommended setup is hybrid: plugin + MCP + hook.
Codex desktop app and Codex CLI use the same `~/.codex` configuration, plugin cache, hooks, and MCP settings. This guide uses `codex` commands because setup is managed by the CLI, but the installed connector applies to both.
Start a session and ask "What was I working on?" You should see your recent focus areas and priorities. Then ask a continuation-style question such as "What did we decide before about this release?" On a healthy setup, Codex should move from Working Memory into retrieval instead of stopping at the briefing. After a short turn, `nmem t search "phrase from that turn" --source codex` should find the captured Codex thread.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Codex desktop app or Codex CLI installed
* `nmem` CLI in your `PATH`
## Setup [#setup]
### Install `nmem` [#install-nmem-step]
```bash
# Option 1: uvx
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from nmem-cli nmem --version
# Option 2: pip
pip install nmem-cli
```
If Nowledge Mem is already running on the same machine through the desktop app, the cleanest setup is **Settings → Preferences → Developer Tools → Install CLI**.
### Install the plugin [#install-the-plugin-step]
If you run into older instructions that copy files into `~/.codex/plugins/cache/local/...`, treat that as legacy fallback only. The primary path is: add the marketplace, install the plugin from that marketplace, then enable it in config.
```bash
codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin
codex plugin add nowledge-mem@nowledge-community
```
If your Codex build only supports the legacy top-level subcommand:
```bash
codex marketplace add nowledge-co/community
```
You can also open Codex `/plugins` and install `nowledge-mem@nowledge-community` from there.
Prefer the sparse marketplace command when your Codex build supports it. Codex only pulls the marketplace metadata and the Codex plugin package instead of cloning the whole community repository, which avoids 30-second clone timeouts on slower networks.
### Enable the plugin [#enable-the-plugin-step]
Put this in `~/.codex/config.toml`:
```toml
[features]
plugins = true
hooks = true
[plugins."nowledge-mem@nowledge-community"]
enabled = true
```
Restart Codex after installation.
The current package includes a local Nowledge Mem MCP server at `http://127.0.0.1:14242/mcp/`. Codex user config wins if you define your own `mcp_servers.nowledge-mem`, so remote Mem and custom local ports stay explicit.
### Enable lifecycle context and thread capture [#enable-lifecycle-context-and-thread-capture-step]
Codex uses hooks for automatic startup context, memory routing, and thread capture. Current Codex builds load hooks from enabled plugins automatically. Older builds used a separate `plugin_hooks` feature gate; the setup script detects that host capability and adds the compatibility flag only when it is still required. Run the plugin's hook setup once after install or update:
```bash
HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
if [ -z "$HOOK_SETUP" ]; then
echo "Hook setup was not found. Open Codex, run /plugins, install nowledge-mem@nowledge-community, then retry."
else
python3 "$HOOK_SETUP"
fi
```
Restart Codex after setup. When Codex asks you to review changed hooks, trust the Nowledge Mem SessionStart, UserPromptSubmit, and Stop hooks; enabling a hook and trusting its command are separate safeguards.
The SessionStart hook injects Context Bundle, falling back to Working Memory when needed. A short UserPromptSubmit hook keeps continuation, review, regression, release, connector, prior-decision, and exact-history work routed to Nowledge search. The Stop hook calls `nmem t save --from codex`, reads the local transcript, and uploads through your normal `nmem` client configuration. Local and remote Mem use the same setup. If Codex sees both the plugin Stop hook and the host-level fallback, the hook skips the duplicate save for the same transcript state.
The same setup also checks your `nmem` client configuration. If `nmem` has a saved API key or a non-default endpoint, it writes a managed Codex MCP block into `~/.codex/config.toml` so Codex uses the same Mem server as the CLI.
On Windows PowerShell, run the installed setup script with the Python launcher:
```powershell
$HookSetup = Get-ChildItem "$env:USERPROFILE\.codex\plugins\cache" -Recurse -Filter install_hooks.py |
Where-Object { $_.FullName -like "*nowledge-mem*" } |
Sort-Object FullName |
Select-Object -Last 1
if ($null -eq $HookSetup) {
Write-Host "Hook setup was not found. Open Codex, run /plugins, install nowledge-mem@nowledge-community, then retry."
} else {
py -3 $HookSetup.FullName
}
```
### If you also use Codex Memory [#if-you-also-use-codex-memory-step]
Codex local Memory and Nowledge Mem can run together, but they are not the same store. Codex Memory is generated state under your local `CODEX_HOME`; Nowledge Mem carries current Working Memory, exact conversations, sourced decisions, Spaces, and knowledge across every connected AI tool.
In **Codex Settings → Personalization**, turn off **Allow memory generation from tool-assisted tasks**. This keeps tasks that used Nowledge MCP, web search, or tool search out of Codex's separate memory generator. You may leave **Enable memories** on if you still want Codex's local recall layer.
The equivalent `~/.codex/config.toml` setting is:
```toml
[memories]
disable_on_external_context = true
```
Without this isolation, Codex can generate a local summary from a task that just retrieved Nowledge context. Future tasks may then answer from that older local summary without consulting the current cross-tool source. Plugin `0.1.26` and newer also inject an explicit routing boundary, but the isolation toggle closes the write-side duplicate-learning loop. The setup script reports this recommendation when needed; it never changes Codex Memory settings for you.
Leaving Codex local Memory off is also a complete setup. Nowledge startup context, search, distillation, and transcript capture continue to work normally.
### Optionally add project-level guidance [#optionally-add-project-level-guidance-step]
Copy or merge the plugin's `AGENTS.md` into your project root for stronger default memory behavior:
```bash
git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community
cp /tmp/nowledge-community/nowledge-mem-codex-plugin/AGENTS.md ./AGENTS.md
rm -rf /tmp/nowledge-community
```
If your project already has an `AGENTS.md`, merge the Nowledge section instead of overwriting. This is the clean way to make Codex do more than the basic startup context check on continuation-heavy repos.
Use your repo's own `AGENTS.md` as the override layer. Treat the package `AGENTS.md` as source text to copy or merge, not as a file to patch inside the Codex plugin install directory.
### Configure remote Mem when needed [#configure-remote-mem-when-needed-step]
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
`nmem` resolves connection settings in this order:
1. `--api-url` / `--api-key` flags
2. `NMEM_API_URL` / `NMEM_API_KEY`
3. `~/.nowledge-mem/config.json`
4. defaults
If Mem is remote, override the bundled local MCP server in `~/.codex/config.toml` too:
```bash
nmem config mcp show --host codex
```
Paste the generated TOML into `~/.codex/config.toml`, or rerun the hook setup if your installed plugin is `0.1.11` or newer. Direct MCP clients do not read `~/.nowledge-mem/config.json` automatically; this keeps Codex MCP and `nmem` pointed at the same Mem server. MCP gives Codex direct tools; `nmem` still powers the plugin-side fallback flows and real `save-thread`.
## Repo-level install (alternative) [#repo-level-install-alternative]
Instead of a shared marketplace source, you can bundle the plugin in a project repo using a local Codex marketplace file. This makes the plugin available to anyone who clones the repo.
```bash
git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community
mkdir -p .agents
cp -r /tmp/nowledge-community/nowledge-mem-codex-plugin ./.agents/nowledge-mem
rm -rf /tmp/nowledge-community
mkdir -p .agents/plugins
```
Create `.agents/plugins/marketplace.json`:
```json
{
"name": "local",
"plugins": [
{
"name": "nowledge-mem",
"source": {
"source": "local",
"path": "./.agents/nowledge-mem"
},
"policy": {
"installation": "INSTALLED_BY_DEFAULT",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}
```
The `path` is relative to the repo root, not to the marketplace file. For this local setup, use:
```toml
[plugins."nowledge-mem@local"]
enabled = true
```
Then run the hook setup from the repo-local plugin:
```bash
python3 ./.agents/nowledge-mem/scripts/install_hooks.py
```
## Update [#update]
If you installed the Codex package before `0.1.14`, refresh the marketplace first. Current Codex builds may refresh the marketplace checkout without reinstalling the already-installed package cache, so the hook setup file or bundled hook changes may still be missing until the package itself is updated.
```bash
(codex plugin marketplace remove nowledge-community || codex marketplace remove nowledge-community || true)
codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin
codex plugin add nowledge-mem@nowledge-community
```
This intentionally re-adds the marketplace with Codex sparse checkout. Older installs used a full clone of the community repository; if Codex reports `git clone marketplace source timed out after 30s` or `early EOF`, this is the recovery path. You can also update or reinstall `nowledge-mem@nowledge-community` from Codex `/plugins`. Restart Codex after the package is updated.
After the package itself is updated, refresh the hook runtime:
```bash
HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
if [ -z "$HOOK_SETUP" ]; then
echo "Hook setup is still missing. Reinstall nowledge-mem@nowledge-community from Codex /plugins, then retry."
else
python3 "$HOOK_SETUP"
fi
```
If the marketplace is not registered yet, run:
```bash
codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin || codex marketplace add nowledge-co/community
```
Then restart Codex. If you are using a repo-local `@local` source, update that local source path instead.
## Skills [#skills]
The plugin skills still matter in the hybrid setup. They teach Codex when to use memory at all, while MCP gives Codex a lower-friction execution path once it decides to act.
| Skill | Trigger | What it does |
| ------------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `$nowledge-mem:working-memory` | Session start, "what am I working on" | Loads your daily Working Memory briefing and prefers MCP `read_working_memory` when available |
| `$nowledge-mem:search-memory` | Prior work, past decisions, "why did we..." | Searches memories and threads with progressive inspection, preferring MCP retrieval when available |
| `$nowledge-mem:save-thread` | Manual save request, or hook setup unavailable | Real Codex transcript import via `nmem t save --from codex` |
| `$nowledge-mem:distill-memory` | Decisions, learnings, procedures emerge | Proactively saves durable insights to memory, preferring MCP writes when available |
| `$nowledge-mem:status` | "Is Mem working?", errors | Checks server connectivity and configuration |
## Nowledge FS for Codex [#nowledge-fs-for-codex]
[Nowledge FS](/docs/nowledge-fs) is the shared path-first layer behind Knowledge Tree. It is not a Codex-only feature. Codex can use the same layer through the MCP server with `mem_fs`, a path-first view across memories, threads, wiki pages, working memory, activities, sources, and artifacts.
```text
mem_fs: recall "why did we change token refresh?" --in /memories -k 5
mem_fs: cat /memories/by-id/.memory.md
mem_fs: ls /memories/by-label/auth
```
If MCP is not available, use the CLI:
```bash
nmem fs recall "session token strategy" --in /memories -k 5
nmem fs grep "JWT rotation" /memories
nmem fs cat /memories/by-id/.memory.md
```
Use `recall` for fuzzy intent, `find` for metadata constraints, `grep` for exact strings, `stat` before loading large bodies, and `cat` after a useful path has been found. `grep` is case-insensitive by default; add `--case-sensitive` for exact casing or `-E` for regex. This preview release is API-backed and works in desktop, web, and remote setups; mounting it as a real folder is planned for a later phase.
## Direct `nmem` Use [#direct-nmem-use]
`nmem` remains the universal fallback and the real Codex thread-import path. The Stop hook uses the same command automatically:
```bash
nmem --json wm read
nmem --json m search "auth token rotation" --mode deep
nmem --json t save --from codex -p . -s "Finished the auth refactor."
nmem --json m add "JWT refresh failures came from clock skew." --title "JWT refresh failures traced to clock skew" --importance 0.9 --unit-type learning -l auth -s codex
```
By default, `nmem t save --from codex` reads sessions from `~/.codex`. If your Codex home lives somewhere else, set `CODEX_HOME` and the save path follows automatically.
To import older Codex sessions, preview first:
```bash
nmem t sync --from codex --all-projects --limit 20
```
Then import:
```bash
nmem t sync --from codex --all-projects --apply
```
Use `-p /path/to/project` instead of `--all-projects` when you only want one project. The command reads local Codex transcript files and writes to the Mem server configured in `nmem`.
## Migrating from Custom Prompts [#migrating-from-custom-prompts]
If you previously used `nowledge-mem-codex-prompts`, the plugin covers everything the prompts did:
1. Install the plugin (see Setup above).
2. Remove old prompts: `rm ~/.codex/prompts/{read_working_memory,search_memory,save_session,distill}.md`
3. The plugin skills replace the prompts one-to-one.
| Old prompt | New skill |
| ------------------------------ | ------------------------------ |
| `/prompts:read_working_memory` | `$nowledge-mem:working-memory` |
| `/prompts:search_memory` | `$nowledge-mem:search-memory` |
| `/prompts:save_session` | `$nowledge-mem:save-thread` |
| `/prompts:distill` | `$nowledge-mem:distill-memory` |
| *(none)* | `$nowledge-mem:status` |
## Troubleshooting [#troubleshooting]
**"Command not found: nmem"**
Install with `pip install nmem-cli` or use `uvx --from nmem-cli nmem`. See [Getting Started](/docs/installation).
**"Cannot connect to server"**
Run `nmem status` and `nmem config client show` for remote setups. See [Remote Access](/docs/remote-access).
**Skills not appearing**
Restart Codex after installing the plugin. Verify three things: the marketplace was added, `nowledge-mem@nowledge-community` was installed with `codex plugin add` or from `/plugins`, and `~/.codex/config.toml` has `[features] plugins = true`, `hooks = true`, and `[plugins."nowledge-mem@nowledge-community"] enabled = true`. Older hosts may also need `plugin_hooks = true`; rerun setup and let it detect that requirement instead of adding the flag by hand. If you intentionally use a repo-local source, use `[plugins."nowledge-mem@local"]`.
**Codex says `unknown field description, expected hooks`**
Update the plugin package to `0.1.19` or newer, then restart Codex:
```bash
(codex plugin marketplace remove nowledge-community || codex marketplace remove nowledge-community || true)
codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin
codex plugin add nowledge-mem@nowledge-community
```
This warning came from a strict Codex hook parser rejecting extra metadata in `hooks/hooks.json`. Current packages keep that file schema-only.
**Using Codex inside WSL**
Install and update the Codex plugin from the same WSL distro that runs Codex. The Windows desktop app can show that a WSL Codex plugin is outdated, but it cannot safely run the update in Windows because that would use the wrong shell, plugin cache, Python, and `~/.codex` home. Copy the update command from Mem and run it inside WSL, then restart Codex there.
**Startup context or Codex threads are not appearing automatically**
Run the hook setup again, then restart Codex:
```bash
HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
test -n "$HOOK_SETUP" && python3 "$HOOK_SETUP"
```
The setup enables the current hook feature, adds the legacy plugin-hook gate only on hosts that still expose it, and keeps a host-level Stop fallback for Codex builds that still need `~/.codex/hooks.json`. Open `/hooks` and make sure the Nowledge Mem SessionStart, UserPromptSubmit, and Stop hooks are both enabled and trusted. Trust is intentionally user-owned, so setup does not bypass it.
**`codex mcp list` shows `Not logged in`**
Update `nmem` so it matches your Mem app/server, install the CLI config from the desktop app if you use local desktop Mem, then rerun the hook setup:
```bash
pip install -U nmem-cli
nmem status
HOOK_SETUP="$(find ~/.codex/plugins/cache -path '*/nowledge-mem/*/scripts/install_hooks.py' -print 2>/dev/null | sort | tail -1)"
test -n "$HOOK_SETUP" && python3 "$HOOK_SETUP"
```
Do not run `codex mcp login nowledge-mem`. That command is for OAuth MCP servers. Nowledge Mem uses the URL and headers generated by `nmem config mcp show --host codex`.
**"plugin is not installed"**
Run `codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin` (or `codex marketplace add nowledge-co/community` on legacy Codex), install with `codex plugin add nowledge-mem@nowledge-community` or from `/plugins`, then verify the plugin key in `~/.codex/config.toml`.
**It only reads Working Memory, but never searches or distills**
Update the package to `0.1.26` or newer, rerun the hook setup, and confirm the bundled `nowledge-mem` MCP server plus the UserPromptSubmit hook are visible in Codex. If Codex local Memory is enabled, turn off **Allow memory generation from tool-assisted tasks**. For stronger repo-specific behavior, merge the package `AGENTS.md` into your project root. If Mem is remote or not on the default local port, add `mcp_servers.nowledge-mem` in `~/.codex/config.toml` to override the bundled endpoint.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Nowledge FS](/docs/nowledge-fs)
* [Gemini CLI](/docs/integrations/gemini-cli)
* [Claude Code](/docs/integrations/claude-code)
* [Remote access](/docs/remote-access)
# Copilot CLI (/docs/integrations/copilot-cli)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Copilot CLI. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="One-minute install"
copilot plugin marketplace add nowledge-co/community
copilot plugin install nowledge-mem@nowledge-community
```
Copilot CLI supports plugins and lifecycle hooks. Install the plugin once, keep
nmem available locally, and Copilot can start with Context Bundle or Working Memory,
search when past context matters, and keep appending your session into Mem
before the host compresses or closes the conversation.
This is the dedicated Nowledge path for GitHub Copilot CLI. It is closer to
Claude Code than to generic MCP: the plugin brings its own hooks, skills, and
capture runtime. At the same time, Copilot still decides when to use the
model-mediated skills, so project guidance such as AGENTS.md still
helps when you want stronger proactive recall and distillation.
Start a new Copilot session and ask What was I working on? You should
see your recent focus and priorities. Then ask Copilot to save or checkpoint the
session and confirm the thread appears in Mem.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* GitHub Copilot CLI installed
* `nmem` CLI in your `PATH`
## Setup [#setup]
### Install `nmem` [#install-nmem-step]
```bash
# Option 1: use the bundled CLI from the Mem desktop app
# Settings → Preferences → Developer Tools → Install CLI
# Option 2: pip
pip install nmem-cli
# Option 3: pipx
pipx install nmem-cli
```
Then verify:
```bash
nmem status
```
On Windows and Linux with the Nowledge Mem desktop app, `nmem` is already bundled.
### Install the plugin [#install-the-plugin-step]
```bash
copilot plugin marketplace add nowledge-co/community
copilot plugin install nowledge-mem@nowledge-community
```
Restart Copilot CLI after installation.
The plugin now runs its capture runtime from its own packaged `hooks/`
directory. Older installs can still fall back to
`~/.copilot/nowledge-mem-hooks/` if that compatibility copy already exists.
### WSL bridge when needed [#wsl-bridge-when-needed-step]
If Copilot CLI runs inside WSL, but `nmem` is installed on Windows through the
Mem desktop app, create this bridge inside WSL:
```bash
mkdir -p ~/.local/bin && cat > ~/.local/bin/nmem << 'SHIMEOF'
#!/bin/bash
python3 - "$@" <<'PY'
import subprocess
import sys
cmd = subprocess.list2cmdline(["nmem.cmd", *sys.argv[1:]])
raise SystemExit(subprocess.run(["cmd.exe", "/s", "/c", cmd]).returncode)
PY
SHIMEOF
chmod +x ~/.local/bin/nmem
```
This lets Copilot running in WSL call the Windows `nmem` cleanly.
### Add project guidance when you want stronger initiative [#add-project-guidance-when-you-want-stronger-initiative-step]
The plugin handles Context Bundle / Working Memory bootstrap and session capture on its own. If
you also want Copilot to search or distill more proactively in
continuation-heavy repos, merge the package `AGENTS.md` into your project root:
```bash
git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community
cp /tmp/nowledge-community/nowledge-mem-copilot-cli-plugin/AGENTS.md ./AGENTS.md
rm -rf /tmp/nowledge-community
```
If your repo already has an `AGENTS.md`, merge the Nowledge section instead of
overwriting the file.
### Configure remote Mem when needed [#configure-remote-mem-when-needed-step]
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
This writes the shared local client config used by the plugin and `nmem`.
## What Happens Automatically [#what-happens-automatically]
The plugin uses Copilot CLI hooks for five things:
* **SessionStart** on startup, resume, and clear: load Context Bundle with `nmem --json context --source-app copilot-cli`, then fall back to Working Memory
* **SessionStart** after compaction: reload Context Bundle or Working Memory and remind Copilot to checkpoint important findings
* **UserPromptSubmit**: keep search and save guidance close to each turn
* **Stop**: capture the recorded Copilot session asynchronously after each response
* **PreCompact** and **SessionEnd**: capture the latest recorded session before compaction and when a session closes
The capture hooks append only the new conversation content. They do not keep
re-importing the whole session each time.
## Skills [#skills]
The Copilot plugin keeps the user-facing surface simple. It does not ship a
separate command-doc layer for save, search, or status. Instead, it relies on
skills and the underlying `nmem` CLI.
| Skill | When it helps | What it does |
| --------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `read-working-memory` | Session start, "what am I working on?" | Loads Context Bundle when available, or today's Working Memory briefing as the lightweight fallback |
| `search-memory` | Prior work, earlier rationale, past discussions | Searches durable memories and prior threads |
| `distill-memory` | A real decision or learning emerged | Saves durable knowledge into Mem |
| `save-thread` | "Save this session", "Checkpoint this" | Saves a concise session summary thread on explicit request |
For direct troubleshooting outside the skill surface, run `nmem status` in your terminal.
## Update [#update]
```bash
copilot plugin marketplace add nowledge-co/community
copilot plugin marketplace update nowledge-community
copilot plugin update nowledge-mem
```
Then restart Copilot CLI.
## Customize Safely [#customize-safely]
Use Copilot's own instruction files instead of editing the installed plugin:
* `.github/copilot-instructions.md` or `.github/instructions/*.instructions.md` for shared repo rules
* `~/.copilot/copilot-instructions.md` for your personal rules across repos
For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Troubleshooting [#troubleshooting]
**`nmem` not found**
Install `nmem-cli` with `pip` or `pipx`, or use the bundled CLI from the Mem desktop app.
**Startup context never appears**
Restart Copilot CLI after installation. Then run `nmem status` to confirm the local client can reach Mem.
**Threads are not appearing in Mem**
Restart Copilot CLI after install or update, then check `~/.copilot/nowledge-mem-hooks/hook-log.jsonl`.
If you are on an older install or local development checkout, you can still run
`scripts/install-hooks.sh` from the source tree as a compatibility fallback.
**Copilot only reads startup context, but rarely searches or distills**
That usually means the bootstrap hook is working, but your repo does not yet
give Copilot strong enough behavioral guidance. Merge the plugin `AGENTS.md`
into your project root, then retry with a continuation-style question.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Codex](/docs/integrations/codex-cli)
* [Claude Code](/docs/integrations/claude-code)
* [Remote access](/docs/remote-access)
# Craft Agent × Nowledge Mem (/docs/integrations/craft-agent)
Paste this into Craft Agent after setup:
```text
Read the Nowledge Mem guide in the nowledge-mem source, check whether Mem is reachable, and tell me what context you can see.
```
Craft Agent can use Nowledge Mem through Craft's workspace source system. The source gives Craft the Mem MCP tools. The guide teaches Craft when to read Working Memory, search prior decisions, and save durable knowledge.
For recorded conversations, use the CLI importer. Craft stores sessions locally as `session.jsonl`; `nmem` reads those files on the Craft machine and uploads normalized threads to your local or remote Mem server.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* Craft Agent is installed
* `nmem` works on the same machine as Craft Agent
```bash
nmem status
```
## Setup [#setup]
Generate the Craft source and guide:
```bash
nmem config mcp show --host craft-agent
```
In the Craft workspace you want to connect:
1. Create `sources/nowledge-mem/`.
2. Save the generated `sourceConfig` JSON as `sources/nowledge-mem/config.json`.
3. Save the generated guide markdown as `sources/nowledge-mem/guide.md`.
4. Restart or reload Craft Agent.
For remote Mem, configure the shared `nmem` client first, then regenerate:
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
nmem config mcp show --host craft-agent
```
## Verify [#verify]
Ask Craft:
```text
Is Nowledge Mem connected? Read my Working Memory or Context Bundle and summarize the current focus.
```
Success means Craft can call the Mem tools from the `nowledge-mem` source and can see your current context.
## Import Craft Sessions [#import-craft-sessions]
Use this when you want the real Craft transcript saved in Mem:
```bash
nmem t sync --from craft-agent --all-projects --limit 20
```
Then import:
```bash
nmem t sync --from craft-agent --all-projects --apply
```
The importer scans Craft workspaces under your Craft config directory. It uses each session's workspace header when available and writes stable `craft-agent-*` thread IDs, so reruns append with deduplication instead of creating duplicate threads.
Useful filters:
```bash
nmem t sync --from craft-agent --session-dir ~/.craft-agent/workspaces --limit 20
nmem t sync --from craft-agent --space work --apply
```
If you keep Craft config somewhere else, set `CRAFT_CONFIG_DIR` or pass `--session-dir`.
## What Is Automatic [#what-is-automatic]
Craft can use memory tools whenever the source and guide are available, but Craft does not need a Nowledge npm package today. The workspace source handles MCP access; `nmem t sync --from craft-agent` handles transcript import.
If Craft adds a stable lifecycle hook later, Nowledge Mem can add live capture on top of the same source name. Until then, treat real session capture as explicit CLI import.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Threads](/docs/threads)
* Craft Agent repo: [craft-ai-agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
# Cumora (/docs/integrations/cumora)
Cumora is an AI teammate workspace. Its agents have personas, can start conversations, and may carry their own internal memory.
Nowledge Mem should not replace that. It should give each Cumora teammate access to the same durable, cross-tool knowledge layer the user already shares with Codex, Claude Code, Pi, OpenClaw, browsers, notes, and the Library.
The important rule: do not give a shared computer-level daemon one `NMEM_AGENT_ID` if several Cumora teammates use it. If Atlas, Iris, Bram, and Nova all inherit the same daemon identity, Mem will treat them as one teammate. That is worse than leaving identity unset.
## Best Current Path [#best-current-path]
Use a two-step setup:
1. Connect the AI coding tool Cumora launches.
2. Add a small Mem AI Identity instruction to each Cumora agent persona.
This works even when Cumora gives you only one local npx or daemon command per computer, because the identity is selected by the agent's instruction, not by the daemon's environment.
## Connect The Runtime [#connect-the-runtime]
Install and verify Nowledge Mem on the computer where Cumora starts the AI tool:
```bash
nmem status
```
Then connect the tool Cumora launches, such as Codex or Claude Code:
* [Codex](/docs/integrations/codex-cli)
* [Claude Code](/docs/integrations/claude-code)
* [Pi](/docs/integrations/pi)
This gives that tool access to Mem tools, Context Bundle / Working Memory, and any session-sync hooks it supports. For example, if Cumora launches Codex or Claude Code and those connectors are installed, those tool sessions can sync through their Nowledge Mem hooks.
## Add The Persona Bridge [#add-the-persona-bridge]
For each long-lived Cumora teammate, create a Mem AI Identity:
```bash
nmem agents upsert atlas \
--name "Atlas" \
--default-space research \
--instructions "Research across the user's knowledge. Cite sources and separate facts from interpretation."
```
`Atlas` is the display name. `atlas` is the stable id. This command only creates the identity record; it is used when the Cumora persona passes `agent_id="atlas"` or when a future per-agent environment sets `NMEM_AGENT_ID=atlas`.
Then add this short block to that Cumora agent's persona or system prompt:
```text
Nowledge Mem:
- At the start of a task, read Context Bundle as agent_id="atlas".
- If the tool supports it, also pass host_agent_id="cumora:atlas".
- Keep source_app as the AI tool when known, such as "codex" or "claude-code".
- For later Nowledge Mem calls, pass agent_id="atlas" again so memory_search, thread_search, read_working_memory, and memory_add use the same identity and default space.
- Save durable decisions, preferences, and procedures when they matter beyond this conversation.
```
If the agent only has CLI access, the same behavior is:
```bash
nmem --json context --agent-id atlas --host-agent-id cumora:atlas --source-app codex
```
Use the returned active space for later commands:
```bash
nmem --json m search "recent research decisions" --space research
nmem --json m add "Atlas learned that ..." -t "Research note" --space research -s codex
```
If the agent has MCP access, prefer passing `agent_id` directly:
```text
read_context_bundle(agent_id="atlas", source_app="codex", host_agent_id="cumora:atlas")
read_working_memory(agent_id="atlas", source_app="codex", host_agent_id="cumora:atlas")
memory_search(query="recent research decisions", agent_id="atlas", source_app="codex")
thread_search(query="last onboarding discussion", agent_id="atlas", source_app="codex")
memory_add(content="Atlas learned that ...", title="Research note", agent_id="atlas", source_app="codex")
```
This is the clean fallback until Cumora exposes per-agent environment variables or an official integration point.
## If Cumora Adds Per-Agent Env [#if-cumora-adds-per-agent-env]
If Cumora later lets each agent set environment variables, move the identity out of the persona prompt and into that per-agent environment:
```bash
NMEM_AGENT_ID=atlas
NMEM_HOST_AGENT_ID=cumora:atlas
```
Do not set these on the shared daemon unless that daemon belongs to exactly one Cumora teammate.
## What Syncs [#what-syncs]
Supported AI-tool sessions can sync. If Cumora launches Codex, Claude Code, Pi, OpenClaw, or another tool with a Nowledge Mem connector, use that connector's normal sync path.
Cumora-native history is different. Nowledge Mem cannot directly import Cumora rooms or Cumora's internal agent memory unless Cumora exposes a local API, export, hook, or per-agent runtime integration point.
Until then, Cumora's own internal memory stays inside Cumora. Nowledge Mem remains the user's cross-tool, cross-agent knowledge layer for the connected AI tools, saved memories, notes, and Library.
## Next [#next]
* [Customize Connector Behavior](/docs/integrations/customize-behavior)
* [Raft](/docs/integrations/raft)
* [Multica](/docs/integrations/multica)
# Cursor (/docs/integrations/cursor)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Cursor. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
The most reliable path today is local install from `~/.cursor/plugins/local/nowledge-mem-cursor`. It works before Marketplace acceptance and uses the same package you would later publish.
If **Nowledge Mem** eventually becomes visible in Cursor Marketplace for your account, you can switch to that path later. The local package path below is the user-ready path now.
The practical benefit is simple: install once, start a new agent session, and Cursor gets the rule, skills, hook, and MCP wiring together.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Cursor IDE installed
* Recommended: `nmem` in your `PATH` if you want automatic Context Bundle / Working Memory bootstrap and resumable handoff creation through the terminal tool
If Nowledge Mem is already running on the same machine through the desktop app, the easiest path is **Settings → Preferences → Developer Tools → Install CLI**. That gives Cursor access to `nmem` for session-start Context Bundle / Working Memory bootstrap and explicit handoff creation.
For real Cursor Agent thread history, Mem reads Cursor's local Agent transcript files from `~/.cursor/projects`. The desktop app can auto-sync them on the same machine. For a deliberate backfill, preview first:
```bash
nmem t sync --from cursor --all-projects
```
Then import after you confirm the list:
```bash
nmem t sync --from cursor --all-projects --apply
```
If you only want one project, point at its transcript folder:
```bash
nmem t sync --from cursor --session-dir ~/.cursor/projects/Users-me-project/agent-transcripts --apply
```
## One-Minute Setup [#one-minute-setup]
### Clone or open the package folder [#clone-or-open-the-package-folder-step]
```bash
git clone https://github.com/nowledge-co/community.git
cd community
```
### Copy the plugin into Cursor's local plugin folder [#copy-the-plugin-into-cursors-local-plugin-folder-step]
```bash
mkdir -p ~/.cursor/plugins/local
rm -rf ~/.cursor/plugins/local/nowledge-mem-cursor
cp -R nowledge-mem-cursor-plugin ~/.cursor/plugins/local/nowledge-mem-cursor
```
If you want faster local iteration, you can try a symlink instead:
```bash
ln -s "$(pwd)/nowledge-mem-cursor-plugin" ~/.cursor/plugins/local/nowledge-mem-cursor
```
Cursor staff have confirmed that local plugin symlink resolution is currently
buggy in practice, so copy-first is the reliable path.
### Reload Cursor [#reload-cursor-step]
Restart Cursor or run **Developer: Reload Window**.
If Cursor still shows Claude Code wording, `save-thread`, or hooks like `beforeSubmitPrompt` and `stop`, remove the older imported `nowledge-mem` package from Cursor first. The local package here should expose only `sessionStart` plus the four Nowledge Mem skills. The local plugin id is `nowledge-mem-cursor` specifically to avoid colliding with that imported package.
### Start a new agent session [#start-a-new-agent-session-step]
For the default same-machine setup, the bundled plugin assets are the intended zero-config path:
* plugin manifest
* rule
* skills
* session-start hook
* local `mcp.json`
If `nmem` is installed, the session-start hook can preload Working Memory into the new Cursor session before the agent begins.
### Configure MCP for remote Mem only [#configure-mcp-for-remote-mem-only-step]
Only if you use remote Mem, open **Settings** (`Cmd/Ctrl+Shift+J`) -> **Features** -> **Model Context Protocol** and update the `nowledge-mem` server URL and headers.
If you also want the `sessionStart` hook and `save-handoff` skill to work against remote Mem, point the local `nmem` client at the same remote server:
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
The split is intentional:
* Cursor MCP settings drive the plugin's memory tools
* `nmem config client ...` drives the terminal-side bootstrap and handoff flow on this machine
## Update [#update]
If you installed through the local plugin folder:
* recommended copied path: replace `~/.cursor/plugins/local/nowledge-mem-cursor` with a fresh copy, then reload Cursor
* optional symlink path: pull the latest `community` changes and reload Cursor, but switch back to copied install if Cursor stops detecting the plugin
If Marketplace support appears later, you can uninstall the local copy and move to Marketplace.
## Customize Safely [#customize-safely]
Use Cursor's own rule files for behavior changes:
* `.cursor/rules/*.mdc`
* `.cursorrules`
Keep the packaged Nowledge Mem rule as the default. Do not patch the installed plugin files under `~/.cursor/plugins/...`. Full map: [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Your First Success State [#your-first-success-state]
You know the plugin is set up correctly when:
* the plugin is installed from `~/.cursor/plugins/local/nowledge-mem-cursor`
* you start a new Cursor agent session
* if `nmem` is installed, Working Memory is already available at the start of the session
* same-machine setup works without hand-editing MCP config
* in remote mode, updating the `nowledge-mem` MCP server is enough to restore the same behavior
* Cursor is not showing a stale Claude-oriented package surface such as `save-thread`, `beforeSubmitPrompt`, or `stop`
## What You Get [#what-you-get]
* Bundled `.cursor-plugin/plugin.json`
* Bundled `hooks/hooks.json` with a `sessionStart` Context Bundle / Working Memory bootstrap
* Bundled `mcp.json` for local Nowledge Mem MCP connectivity
* An always-on rule for Working Memory, routed recall, distillation, and handoff semantics
* Four skills: `read-working-memory`, `search-memory`, `distill-memory`, and `save-handoff`
* Real Cursor Agent transcript import through Mem desktop auto-sync or `nmem t sync --from cursor`
## What Users Usually Care About [#what-users-usually-care-about]
For a fresh install, the important answers are simple:
* local Mem: install the plugin and start a new session
* remote Mem: install the plugin, then update the `nowledge-mem` MCP server URL and headers; if you want bootstrap and handoff too, also point `nmem` at the same remote server
* best Cursor experience: keep `nmem` installed so the session-start hook can preload Working Memory and Cursor can create handoff summaries when needed
## Important Constraint [#important-constraint]
This package intentionally does **not** expose `save-thread`.
Cursor's plugin surface still does not expose a direct live transcript hook, so summary-only behavior must stay named `save-handoff`, not `save-thread`. Real Cursor Agent threads are imported by Mem desktop or `nmem t sync --from cursor`, which reads Cursor's local `agent-transcripts` JSONL files and appends deduplicated messages into Mem.
## Package Shape [#package-shape]
This package is already arranged in Cursor's plugin format:
```text
.cursor-plugin/plugin.json
rules/nowledge-mem.mdc
skills/*/SKILL.md
hooks/hooks.json
hooks/session-start.mjs
mcp.json
```
Cursor's local plugin folder expects `.cursor-plugin/plugin.json` at the package root. This package already matches that contract, so the local install path above is stable and direct.
## Marketplace Later [#marketplace-later]
If Cursor Marketplace accepts the package later, install **Nowledge Mem** there and keep the same behavior. Until then, the local plugin folder is the right path for users.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code)
* [Gemini CLI](/docs/integrations/gemini-cli)
* [Remote access](/docs/remote-access)
# Customize Integration Behavior (/docs/integrations/customize-behavior)
If you tune how an integration behaves, that change should survive the next plugin update.
The safe rule is simple: put your rule in the host's own instruction file or settings surface. Do not edit installed plugin files inside a cache or marketplace directory.
Pick the tool you use, add one small rule in the file or settings listed below, then update the plugin once later to confirm your tweak still survives.
## Where To Put Your Changes [#where-to-put-your-changes]
| Tool | Put your custom behavior here | Best for |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| **Codex** | project `AGENTS.md` | Repo-specific memory behavior shared by Codex desktop app and CLI |
| **Claude Code** | `CLAUDE.local.md` for personal rules, `CLAUDE.md` for shared repo rules | Personal tweaks or team-wide repo guidance |
| **Copilot CLI** | `.github/copilot-instructions.md` or `.github/instructions/*.instructions.md` for shared repo rules, `~/.copilot/copilot-instructions.md` for personal rules | Shared or personal Copilot guidance |
| **Cursor** | `.cursor/rules/*.mdc` or `.cursorrules` | Project-local Cursor behavior |
| **Gemini CLI** | project `GEMINI.md`, optional `~/.gemini/GEMINI.md` | Shared repo rules or personal defaults |
| **Hermes Agent** | `HERMES.md` for repo rules, `~/.hermes/SOUL.md` for personal rules | Repo-specific or global Hermes behavior |
| **OpenCode** | project `AGENTS.md`, `~/.config/opencode/AGENTS.md`, or files listed in `opencode.json` `instructions` | Shared or personal OpenCode guidance |
| **Pi** | project `AGENTS.md` | Project-local Pi guidance |
| **OpenClaw** | OpenClaw plugin settings and OpenClaw's own prompt or agent config | Behavior toggles and custom prompting |
| **Alma** | Alma plugin settings and the optional native `nowledge-mem` Skill | Recall and capture behavior, extra instructions |
| **Bub** | Bub's own runtime prompt or config, plus shared `nmem` config | Bub-specific behavior and connection settings |
| **Droid** | Droid's own prompt or instruction surface, plus shared `nmem` config | Droid-specific behavior and connection settings |
| **Raycast** | Raycast preferences | Fixed launcher behavior such as server, key, and optional space |
## What Not To Do [#what-not-to-do]
* Do not edit files inside installed plugin directories such as `~/.codex/...`, `~/.copilot/installed-plugins/...`, `~/.cursor/plugins/...`, or similar cache paths.
* Do not patch bundled skills in place and expect updates to preserve those changes.
* Do not invent a new override filename unless the host actually reads it.
## What Success Looks Like [#what-success-looks-like]
Your setup is in a good state when all three are true:
1. Your custom rule lives in a file or settings surface the host actually owns.
2. The integration still works after a normal plugin or extension update.
3. Your behavior tweak is still active after that update without re-editing installed files.
## Good First Tweaks [#good-first-tweaks]
* "Search prior release work before answering regression questions."
* "Prefer saving Chinese notes when the user is working in Chinese."
* "Be more aggressive about thread search when the user asks what we decided before."
Keep the rule short. The goal is to shape behavior, not replace the whole integration guide.
## Multi-Agent Orchestrators [#multi-agent-orchestrators]
If another app launches your agents for you, give each named worker a stable Mem AI Identity instead of letting every child process share the default identity.
```bash
nmem agents upsert cindy \
--name "Cindy" \
--default-space onboarding \
--instructions "Help with onboarding. Explain one step at a time."
```
This creates the Mem AI Identity named Cindy. Its command and environment ID is `cindy`. This command only creates the identity record; it does not make every Codex session use Cindy.
Then configure that worker's environment:
```bash
NMEM_AGENT_ID="cindy"
```
The identity is portable. You can move Cindy from Raft to another orchestrator, or from Codex to Pi, as long as the new AI tool is connected to Mem and receives the same `NMEM_AGENT_ID`.
Only add `NMEM_SPACE="onboarding"` when this whole run should override the identity's default space. Keep `source_app` as the AI tool being launched. For example, a Codex worker launched by an orchestrator should still read Context Bundle as Codex. `NMEM_HOST_AGENT_ID` is an advanced external alias, not a second required identity field.
If you want a variation of the same persona, create a new identity such as `cindy-reviewer` instead of changing every launcher setting. The new identity can start from Cindy's Rules, then evolve separately.
For the Raft screenshot walkthrough, see [Raft](/docs/integrations/raft).
## Next [#next]
* [Connectors overview](/docs/integrations)
* [Codex](/docs/integrations/codex-cli)
* [Claude Code](/docs/integrations/claude-code)
* [Copilot CLI](/docs/integrations/copilot-cli)
# Droid (/docs/integrations/droid)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Droid. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Add the Nowledge community marketplace, install `nowledge-mem@nowledge-community`, run `nmem status` once, then start a new Droid session.
Droid gets a native connector surface for Context Bundle / Working Memory startup context, routed recall, distillation, status checks, and resumable handoffs. It intentionally does **not** claim `save-thread` yet.
Droid is a good fit for Nowledge Mem because Factory plugins can bundle hooks, commands, and skills into one product surface while letting `nmem` stay the execution layer underneath.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Factory Droid installed
* `nmem` in your `PATH`
If Nowledge Mem is already running on the same machine through the desktop app, the easiest path is still **Settings → Preferences → Developer Tools → Install CLI**. That gives Droid a clean `nmem` path for both local and remote setups.
You can also install `nmem` standalone:
```bash
# Option 1: pip
pip install nmem-cli
# Option 2: uvx
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from nmem-cli nmem --version
```
## One-Minute Setup [#one-minute-setup]
### Add the Nowledge community marketplace [#add-the-nowledge-community-marketplace-step]
```bash
droid plugin marketplace add https://github.com/nowledge-co/community
```
### Run `nmem status` once [#run-nmem-status-once-step]
For the default same-machine setup, it should point to `http://127.0.0.1:14242`.
### Start a new Droid session [#start-a-new-droid-session-step]
The plugin will load Context Bundle when available, fall back to Working Memory, and make its commands and skills available inside Droid.
## Update [#update]
```bash
droid plugin marketplace update nowledge-community
droid plugin update nowledge-mem@nowledge-community
```
## Customize Safely [#customize-safely]
Droid does not yet expose a separate durable instruction file for this package.
* Use Droid's own prompt or instruction surfaces when you want different memory style or saving behavior
* Keep the installed plugin package untouched so marketplace updates stay clean
For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## What You Get [#what-you-get]
* Context Bundle / Working Memory bootstrap at session start, resume, clear, and compaction
* Routed recall across memories and prior sessions
* Distillation into durable memories
* Explicit handoff creation when you want a resumable checkpoint
* One stable remote path through `nmem`
## Commands [#commands]
* `/nowledge-read-working-memory`
* `/nowledge-search-memory`
* `/nowledge-distill-memory`
* `/nowledge-save-handoff`
* `/nowledge-status`
## Remote Mem [#remote-mem]
The recommended remote setup is:
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
That writes the shared local client config for this machine and keeps Droid aligned with the same contract used by Gemini, Codex, and other `nmem`-based paths.
## Important Constraint [#important-constraint]
This package intentionally exposes `save-handoff`, not `save-thread`.
That distinction matters:
* `save-thread` should mean importing the real recorded session messages
* `save-handoff` means storing a concise resumable summary
Droid does not yet have a real Nowledge transcript importer, so the plugin keeps the boundary honest instead of pretending a summary is a full session save.
## Local Checkout Fallback [#local-checkout-fallback]
If you prefer validating from a local checkout:
```bash
git clone https://github.com/nowledge-co/community.git
cd community
droid plugin marketplace add .
droid plugin install nowledge-mem@nowledge-community
```
This works because the `community` repository publishes a repository-level Factory marketplace manifest and the Droid plugin as one package inside it.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Threads](/docs/threads)
* [Cursor](/docs/integrations/cursor)
* [Gemini CLI](/docs/integrations/gemini-cli)
* [Remote access](/docs/remote-access)
# Gemini CLI (/docs/integrations/gemini-cli)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Gemini CLI. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Google has replaced Gemini CLI with **Antigravity CLI** (`agy`). Gemini CLI stopped serving individual-tier accounts on **June 18, 2026**. If you are migrating, see the [Antigravity CLI guide](/docs/integrations/antigravity-cli) — the Nowledge Mem extension converts via `agy plugin import gemini`.
Install `Nowledge Mem` from the official Gemini Extensions Gallery, restart Gemini CLI, and get both bundled MCP tools and `nmem` lifecycle capture.
You can still install from GitHub or a local checkout at the end of this page. The official gallery path below is now the default recommendation.
For most users, the mental model is simple: install the extension from the gallery, make sure `nmem` works once, then start a new Gemini session. The extension includes a local MCP connection for retrieval and memory writes; `nmem` still handles startup context, real thread save, status, and remote client config.
## Before You Start [#before-you-start]
* Nowledge Mem running locally ([installation](/docs/installation)) or a reachable remote Mem server
* Gemini CLI installed
* `nmem` in your `PATH`
If Nowledge Mem is already running on the same machine through the desktop app, the easiest path is **Settings → Preferences → Developer Tools → Install CLI**. That installs the bundled `nmem` CLI and points it at the default local Mem server.
You can also install `nmem` standalone:
```bash
# Option 1: pip
pip install nmem-cli
# Option 2: uvx
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --from nmem-cli nmem --version
```
## One-Minute Setup [#one-minute-setup]
### Find Nowledge Mem in the gallery [#find-nowledge-mem-in-the-gallery-step]
Open the **Gemini CLI Extensions Gallery** and search for **Nowledge Mem**.
### Install and restart [#install-and-restart-step]
Install the extension, then restart Gemini CLI.
### Run `nmem status` once [#run-nmem-status-once-step]
For the default same-machine setup, this should point to `http://127.0.0.1:14242 (default)`.
### Open a new Gemini CLI session [#open-a-new-gemini-cli-session-step]
The extension will load `GEMINI.md`, discover its commands, expose the bundled MCP tools, and make the bundled skills available automatically.
## Update [#update]
```bash
gemini extensions update nowledge-mem-gemini-cli
```
If you prefer the gallery, opening the Gemini CLI Extensions Gallery and updating Nowledge Mem reaches the same result. The important part is to start a fresh Gemini session after the update.
## Import Older Sessions [#import-older-sessions]
Automatic capture starts after the extension is installed. To bring older Gemini CLI sessions into Nowledge Mem, preview first:
```bash
nmem t sync --from gemini-cli --all-projects --limit 20
```
Then import:
```bash
nmem t sync --from gemini-cli --all-projects --apply
```
Use `-p /path/to/project` instead of `--all-projects` when you only want one project. The command reads local Gemini CLI session files on this machine and writes to the Mem server configured in `nmem`.
## Customize Safely [#customize-safely]
Use Gemini's own context files for behavior changes:
* project `GEMINI.md`
* optional `~/.gemini/GEMINI.md` for personal defaults
If the rule grows, split it into files and import them with `@file.md`. Do not edit the installed extension files directly. Full map: [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Your First Success State [#your-first-success-state]
You know Gemini is wired correctly when:
* the gallery install succeeds
* `nmem status` returns successfully
* a new Gemini session exposes the Nowledge commands
* Context Bundle or Working Memory appears at the start of a fresh session when there is context to show
* `save-thread` imports a real Gemini session, and long sessions are saved before compression as well as at session end
## Remote Mem [#remote-mem]
The recommended remote setup is:
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
That writes the shared local client config for this machine. `nmem t save --from gemini-cli` reads Gemini's local session files on the machine where Gemini is running, then uploads normalized thread messages to Mem. The remote Mem server does not need direct access to `~/.gemini`.
For Gemini MCP tools in remote mode, define a `nowledge-mem` server in Gemini `settings.json`. Gemini gives user settings precedence over the extension's bundled local MCP server:
```bash
nmem config mcp show --host gemini-cli
```
Paste the generated JSON into Gemini's `settings.json`. Direct MCP clients do not read `~/.nowledge-mem/config.json` automatically; this keeps Gemini MCP and `nmem` pointed at the same Mem server.
## What You Get [#what-you-get]
* Gemini-native Context Bundle / Working Memory startup context, hooks, commands, and skills
* Bundled local MCP tools for retrieval and memory writes
* Full session capture through `nmem t save --from gemini-cli`, including before context compression and at session end
* Direct `nmem` composition whenever the built-in commands are too narrow
* Clean local and remote auth through `nmem`
## Commands [#commands]
* `/nowledge:read-working-memory`
* `/nowledge:search-memory `
* `/nowledge:distill-memory`
* `/nowledge:save-thread`
* `/nowledge:save-handoff`
* `/nowledge:status`
## Thread Save And Handoff [#thread-save-and-handoff]
Gemini supports two distinct save paths, and they should stay distinct:
* `save-thread` imports the real Gemini session through `nmem t save --from gemini-cli`
* `save-handoff` stores a concise resumable summary for restart and continuation
The extension also runs the same thread import before Gemini compresses context and when the session ends. That keeps the full recorded conversation searchable without turning handoff summaries into fake transcripts.
## Manual Install [#manual-install]
If you prefer installing from GitHub or a local checkout, use this path:
```bash
git clone https://github.com/nowledge-co/nowledge-mem-gemini-cli.git
cd nowledge-mem-gemini-cli
gemini extensions link .
```
Gemini's official docs also support `gemini extensions install ` for GitHub or local sources, and `gemini extensions link ` for local development. For most users, the listed gallery install path above is the simplest choice.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code)
* [Codex](/docs/integrations/codex-cli)
* [Remote access](/docs/remote-access)
# Grok Build (/docs/integrations/grok)
This page is for **Grok Build**, xAI's coding agent with plugins, hooks, skills, and local `~/.grok/` sessions. It is not the setup path for the consumer Grok chat experience on grok.com or x.com. For web Grok conversations, use the [browser extension guide](/docs/integrations/browser-extension) or the [Grok Web connector](/integrations/grok-web).
Nowledge Mem connects to Grok Build through its plugin system. Install it once, restart Grok Build, and new coding-agent sessions can start with your Mem context and save real transcript history back into Mem.
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Grok Build. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Paste that into Grok Build if you want the agent to do the setup. If you prefer the terminal, use the steps below.
## What success looks like [#what-success-looks-like]
After setup, start a fresh Grok Build session and ask "What was I working on?" It should receive Context Bundle or Working Memory. After one normal turn, this should find the captured thread:
```bash
nmem t search "a phrase from the Grok Build turn" --source grok
```
## Requirements [#requirements]
* Grok Build installed and signed in
* `nmem` available on the same machine that runs Grok Build
* Nowledge Mem desktop app running locally, or `nmem` configured for your remote Mem server
If Grok Build runs on the same Mac as the Mem desktop app, install the CLI from **Settings → Preferences → Developer Tools → Install CLI**. If Grok Build runs on another machine, install the standalone CLI there:
```bash
python3 -m pip install --user nmem-cli
# or
pipx install nmem-cli
```
## Install [#install]
```bash
grok plugin install nowledge-co/community#nowledge-mem-claude-code-plugin --trust
```
Restart Grok Build after installation.
The package is shared with our Claude Code connector because Grok Build can load Claude-compatible plugin assets. The hook detects Grok Build at runtime, so its sessions are saved as `source=grok`, not as Claude Code.
## Update [#update]
```bash
grok plugin update nowledge-mem
```
Restart Grok Build after updating.
## Import older Grok Build sessions [#import-older-grok-build-sessions]
Automatic capture starts after the plugin is installed. To backfill older Grok Build sessions, preview first:
```bash
nmem t sync --from grok --all-projects --limit 20
```
Then import:
```bash
nmem t sync --from grok --all-projects --apply
```
Use `-p /path/to/project` instead of `--all-projects` when you only want one project. The command reads Grok Build's local `~/.grok/sessions` files on this machine and writes to the Mem server configured in `nmem`.
## Remote Mem [#remote-mem]
For remote Mem, configure this machine once:
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
The Grok Build hook still reads local session files on the machine where Grok Build runs, then uploads normalized messages through `nmem`. The remote server does not need filesystem access to `~/.grok`.
## Customize behavior [#customize-behavior]
Do not edit the installed plugin files under `~/.grok/installed-plugins`. Put behavior changes in Grok Build project rules or the project instruction files it already reads.
For multi-agent launchers, set `NMEM_AGENT_ID=` before launching the Grok Build worker when that worker represents a stable long-term AI identity. Add `NMEM_SPACE` only when the whole run should be forced into one Mem space.
## What the connector includes [#what-the-connector-includes]
* Session-start Context Bundle / Working Memory injection
* Guided memory search and distillation skills
* `/save`, `/search`, `/sum`, and `/status` commands
* Stop and PreCompact hooks that call `nmem t save --from grok`
* Historical import through `nmem t sync --from grok`
## Troubleshooting [#troubleshooting]
**`nmem` is not found**
Install the CLI on the same machine that runs Grok Build, then run `nmem status`.
**The Grok Build thread is not appearing**
Restart Grok Build after install or update. Then run:
```bash
nmem --json t save --from grok -p .
```
If that works, the connection is healthy and the hook will keep new sessions current.
**You see Claude Code wording in the package**
That is expected in a few shared package filenames. The runtime behavior is Grok Build-aware: hooks pass `--source-app grok` and `nmem t save --from grok`.
## Related [#related]
* [Claude Code](/docs/integrations/claude-code)
* [Codex](/docs/integrations/codex-cli)
* [Cursor](/docs/integrations/cursor)
* [Connectors overview](/docs/integrations)
# Hermes Agent × Nowledge Mem (/docs/integrations/hermes)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Hermes Agent. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="One-command setup (plugin)"
bash <(curl -sL https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.sh)
```
```powershell title="Windows PowerShell"
irm https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.ps1 | iex
```
Hermes v0.7.0+ supports memory providers. Install the plugin once for built-in behavior: Context Bundle loads at session start when available, relevant memories surface before each turn, and Hermes captures cleaned transcript turns into Mem threads while the conversation runs. No SOUL.md guidance needed.
Hermes keeps new memory providers outside the core `hermes-agent` repository. The installer on this page is the supported Nowledge Mem path: it places the provider in `~/.hermes/plugins/nowledge-mem/`, where Hermes loads it through the same memory-provider lifecycle.
Your cross-tool knowledge, accessible in every Hermes session. Decisions from Claude Code, preferences from Cursor, insights from ChatGPT: one knowledge graph, always available.
Install the plugin, restart Hermes, and start a new session. Send one short message that includes a unique phrase, then cleanly exit, run `/new`, or run `/reset`. `nmem t search "that phrase" --source hermes` should find the captured Hermes thread. If your Mem library already has memories, also ask "what decisions have I made recently?" and Hermes should search your knowledge graph without you pointing it at a tool.
The plugin captures new Hermes sessions as they run. To import conversations that already exist in `~/.hermes/state.db`, run a historical sync from the machine where Hermes is installed:
```bash
nmem t sync --from hermes # preview only
nmem t sync --from hermes --apply # import into Mem
```
This is the right path for remote Mem too: your laptop reads the local Hermes database, then uploads normalized threads to the Mem server configured in `nmem status`.
## Before You Start [#before-you-start]
* **Nowledge Mem** running locally ([installation](/docs/installation)) or a reachable remote server
* **Hermes Agent** v0.7.0+ installed (v0.6.x works with MCP mode)
* **`nmem` CLI** available in `PATH`. If the desktop app is on this machine, use **Settings → Preferences → Developer Tools → Install CLI**. On a remote-only machine, install it with `pip install nmem-cli`.
```bash
nmem status # Nowledge Mem is running
hermes --version # Hermes is available
```
## Setup [#setup]
### Plugin install (recommended) [#plugin-install-recommended-step]
```bash
bash <(curl -sL https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.sh)
```
Installs the native memory provider plugin. Restart Hermes after running.
On Windows, use the native PowerShell installer; Git Bash and WSL are not required:
```powershell
irm https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.ps1 | iex
```
Or install manually:
1. Copy plugin files to `~/.hermes/plugins/nowledge-mem/`:
```bash
mkdir -p ~/.hermes/plugins/nowledge-mem
cd ~/.hermes/plugins/nowledge-mem
for f in plugin.yaml __init__.py provider.py client.py; do
curl -sLO "https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/$f"
done
```
2. Set the provider in `~/.hermes/config.yaml`:
```yaml
memory:
provider: "nowledge-mem"
```
3. Restart Hermes.
### MCP mode (Hermes \< v0.7.0) [#mcp-mode-hermes--v070-step]
If you are on an older version of Hermes or prefer a standard MCP connection:
```bash
bash <(curl -sL https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.sh) --mcp
```
```powershell title="Windows PowerShell"
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.ps1))) -Mcp
```
This adds the MCP server to `config.yaml` and installs behavioral guidance in `~/.hermes/SOUL.md`. Tools appear with the `mcp_nowledge_mem_` prefix.
Without behavioral guidance, MCP mode gives Hermes tools but no instruction on when to use them proactively. If Hermes recalls but never saves, this is usually why. The plugin mode does not need guidance because behavior is built into the provider lifecycle.
### Verify [#verify-step]
First verify thread capture with an empty-library-safe check. In Hermes, send:
```
Please reply with: hermes nmem smoke test
```
Then exit cleanly, run `/new`, or run `/reset` so Hermes performs its final thread flush. In a terminal, check:
```bash
nmem t search "hermes nmem smoke test" --source hermes
```
You should see the Hermes thread. After that, if your Mem library already has memories, ask Hermes something that depends on past work:
```text
What decisions have I made recently?
```
In plugin mode, Hermes should call `nmem_search`. In MCP mode, it should call `mcp_nowledge_mem_memory_search`. Then ask Hermes to save a conclusion or watch whether it chooses the native `nmem_save` tool when the conversation reaches a durable decision.
## What Happens Automatically [#what-happens-automatically]
The plugin hooks into Hermes' memory provider lifecycle. No manual tool calls needed for these:
* **Context Bundle** loads at the start of every session when available, with Working Memory fallback on older CLIs
* **Relevant memories** surface before each turn (proactive recall)
* **User profile facts** from Hermes sync to your cross-tool knowledge graph
* **Session transcripts** are captured into Mem threads as turns complete, with a final delta flush when Hermes exits, starts a new session, or resets cleanly
* **Compression recovery hint** is provided on Hermes builds that consume provider compression output
In MCP mode, these behaviors depend on the SOUL.md guidance and are not guaranteed.
## Hermes Memory vs Nowledge Mem [#hermes-memory-vs-nowledge-mem]
Hermes has a built-in memory system for facts specific to Hermes sessions. Nowledge Mem is complementary: it stores knowledge that spans tools. Use both:
* **Hermes memory**: Hermes-specific preferences, environment details, tool quirks
* **Nowledge Mem**: Decisions, procedures, and learnings that future sessions in any tool should know about
The plugin automatically mirrors user profile facts from Hermes to Nowledge Mem, so cross-tool knowledge stays in sync.
## What You Can Do [#what-you-can-do]
**Find knowledge from other tools.** Ask "what did we decide about the database?" and Hermes searches across decisions you made in Claude Code, insights from ChatGPT, notes from Cursor.
**Save knowledge for everywhere.** When you reach a conclusion in Hermes, it saves to your knowledge graph so your next Claude Code session, Cursor project, or ChatGPT conversation can find it too.
**Search past conversations.** Find past conversations by keyword across every tool. Retrieve the full exchange with pagination.
**Keep Hermes sessions searchable.** The provider captures cleaned `user` / `assistant` turns into a Mem thread while the conversation runs. A clean exit, `/new`, or `/reset` performs a final delta flush. The first write for each Hermes `session_id` imports the thread; later writes for the same session append only the new turns.
**Backfill older Hermes sessions.** Historical Hermes conversations live in `~/.hermes/state.db`. Run `nmem t sync --from hermes` to preview them, then add `--apply` to import. The command is safe to rerun: it reuses Hermes `session_id` as the Mem thread ID and appends with message deduplication.
In MCP mode, you also get graph exploration tools to trace how decisions evolved and discover related memories.
## Tools [#tools]
Plugin mode uses clean `nmem_` names. MCP mode uses the `mcp_nowledge_mem_` prefix.
| Plugin | MCP mode tool name | Purpose |
| ---------------------- | ---------------------------------------- | ----------------------------------------------- |
| `nmem_search` | `mcp_nowledge_mem_memory_search` | Search memories |
| `nmem_save` | `mcp_nowledge_mem_memory_add` | Save or upsert a decision, insight, or learning |
| `nmem_update` | `mcp_nowledge_mem_memory_update` | Refine an existing memory |
| `nmem_delete` | `mcp_nowledge_mem_memory_delete` | Remove one or more memories |
| `nmem_thread_search` | `mcp_nowledge_mem_thread_search` | Search past conversations |
| `nmem_thread_messages` | `mcp_nowledge_mem_thread_fetch_messages` | Fetch messages from a thread |
MCP mode also includes `list_memory_labels`, `memory_neighbors`, and `memory_evolves_chain`. These will be added to the plugin when the `nmem` CLI supports them.
## Configuration [#configuration]
No configuration needed for local use. The plugin uses the shared `nmem` client config for server URL and API key. Normal memory operations go through `nmem`; long transcript payloads are sent directly to the Mem API.
If the Nowledge Mem desktop app is on the same machine, `nmem` is already bundled. For remote-only setups without the desktop app: `pip install nmem-cli`.
### Remote access [#remote-access]
Configure the local `nmem` client to point at your remote server:
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
This updates the client-side connection settings for the machine running Hermes. It is separate from server-side Access Anywhere or LAN bind configuration on the Mem host.
The only plugin-specific setting is request timeout, in `~/.hermes/nowledge-mem.json`:
```json
{
"timeout": 60
}
```
### Spaces [#spaces]
Hermes supports three clean mapping levels:
* `space`: one fixed lane for this Hermes profile
* `space_by_identity`: a small explicit map from Hermes identities to named spaces
* `space_template`: one derived lane per Hermes identity, for example `agent-{identity}`
If none of those are set, Hermes can still inherit `NMEM_SPACE`.
For MCP mode, update the URL directly in `config.yaml`:
```yaml title="~/.hermes/config.yaml"
mcp_servers:
nowledge-mem:
url: "https://your-server/mcp"
headers:
Authorization: "Bearer your-key"
timeout: 120
```
See [Access Mem Anywhere](/docs/remote-access).
## Update [#update]
Use the same mode you installed with:
* Plugin mode, the default for Hermes v0.7.0+: re-run the setup command without flags, then restart Hermes.
* MCP mode, for Hermes v0.6.x or a deliberate standard MCP setup: re-run the setup command with `--mcp`, then restart Hermes.
```bash
# Plugin mode
bash <(curl -sL https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.sh)
# MCP mode
bash <(curl -sL https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.sh) --mcp
```
The MCP tools themselves are served by Nowledge Mem and update with the desktop app. The Hermes plugin files update through the setup script.
After updating, the script prints the version and endpoint from the files Hermes will load:
```text
Installed version: 0.5.18
Thread import endpoint: /threads/import
```
If those lines still show an old version or a different endpoint, Hermes is reading a different `HERMES_HOME`. Set `HERMES_HOME` to the profile you use to launch Hermes, run the setup command again, then restart Hermes.
## Disable or Roll Back [#disable-or-roll-back]
Quit Hermes before changing files.
* Plugin mode: set `memory.provider` in `~/.hermes/config.yaml` back to your previous provider, or remove that line if you did not use Hermes memory before. Then remove `~/.hermes/plugins/nowledge-mem`. On older Hermes builds that needed a compatibility copy, also remove `~/.hermes/hermes-agent/plugins/memory/nowledge-mem`.
* MCP mode: remove the `mcp_servers.nowledge-mem` block from `~/.hermes/config.yaml`. If you no longer want the behavior guidance, remove the section headed `# Nowledge Mem for Hermes` from `~/.hermes/SOUL.md`.
* Restart Hermes and run `hermes --version` plus `nmem status` to confirm the host and Mem client are still healthy.
## Customize Safely [#customize-safely]
Use Hermes' own guidance files, not the installed plugin directory:
* `~/.hermes/SOUL.md` for personal default behavior across sessions
* `HERMES.md` at the project root for repo-specific rules
Do not patch the installed Nowledge Mem plugin files under `~/.hermes/plugins/`. For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Troubleshooting [#troubleshooting]
**Cannot connect to Nowledge Mem.** Confirm the server is running with `nmem status`. Check that the URL matches the address shown by `nmem status`.
**Hermes recalls but never saves durable memories (MCP mode).** Behavioral guidance is missing. Run the setup command, then restart Hermes. The guidance must be in `~/.hermes/SOUL.md` (always loaded) or a `HERMES.md` at the git root. In plugin mode, recall and transcript capture are built into the provider lifecycle and do not depend on guidance.
**Hermes threads are not appearing in Mem.** The provider captures completed turns and also flushes at real session boundaries. Test with a normal completed turn, then try a clean exit, `/new`, or `/reset`. If Hermes is killed abruptly during a turn, that unfinished turn may never reach the provider.
**An agent says `client.py` differs from community/main.** That usually means Hermes is running a stale local plugin copy. Re-run the plugin setup command, confirm it prints `Thread import endpoint: /threads/import`, and restart Hermes. Use `SOUL.md` or `HERMES.md` for custom behavior instead of editing files under `~/.hermes/plugins/nowledge-mem/`.
**Older Hermes sessions are missing.** This is expected until you run a historical import. The desktop watcher does not read Hermes' SQLite database. Run `nmem t sync --from hermes` to preview older sessions from `~/.hermes/state.db`, then run `nmem t sync --from hermes --apply` when the preview looks right.
**Tools not appearing (plugin).** Confirm `memory.provider: "nowledge-mem"` in `config.yaml` and plugin files exist in `~/.hermes/plugins/nowledge-mem/`. Restart Hermes.
**Tools not appearing (MCP).** Confirm the `mcp_servers.nowledge-mem` block in `config.yaml`. Restart Hermes. Verify the YAML is valid (correct indentation, no tabs).
**Slow responses.** Default timeout is 30 seconds. Increase in `nowledge-mem.json` (plugin) or `config.yaml` (MCP). If the issue persists, check `nmem status` for server health.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code) · [OpenCode](/docs/integrations/opencode) · [Pi](/docs/integrations/pi) · [OpenClaw](/docs/integrations/openclaw) · [Alma](/docs/integrations/alma) · [Bub](/docs/integrations/bub)
* Source: [nowledge-mem-hermes](https://github.com/nowledge-co/community)
# Connectors (/docs/integrations)
> API reference page. OpenAPI operation details could not be extracted from this page.
# Kimi Code × Nowledge Mem (/docs/integrations/kimi-code)
Paste this into Kimi Code:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Kimi Code. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Kimi Code can use Nowledge Mem through a Kimi-native package. It loads Mem guidance at session start, connects to Mem through MCP, and can sync Kimi Code conversations into Mem Threads with a local lifecycle hook.
Recent Kimi Code builds load those hooks directly from `kimi.plugin.json`, so the connector now feels native: install the package, enable it, reload, and Kimi Code can start reading memory and saving sessions. Older Kimi Code sessions still use the same safe backfill command: preview first, then import with `nmem t sync --from kimi-code --apply`.
This guide is for **Kimi Code**, the terminal and IDE coding agent. Kimi web chat is covered by the [Browser Extension](/docs/integrations/browser-extension). Kimi Work is a separate desktop product with its own embedded runtime; use the [Kimi Work guide](/docs/integrations/kimi-work) for that setup.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* Kimi Code is installed
* `nmem` 0.9.19 or newer works on the same machine as Kimi Code. Kimi Code thread sync depends on the CLI support for `--from kimi-code`.
```bash
nmem status
nmem --version
```
If `nmem` exists but rejects `t sync --from kimi-code`, `config mcp show --host kimi-code`, or another Kimi-specific command, update the CLI before debugging MCP or session sync:
* Desktop-bundled CLI: open Mem and run **Settings → Preferences → Developer Tools → Install bundled CLI** again.
* PyPI CLI: `python3 -m pip install --user --upgrade nmem-cli`
* pipx CLI: `pipx upgrade nmem-cli`
If Kimi Code runs on a different machine from the desktop app, install the standalone CLI there first:
```bash
python3 -m pip install --user nmem-cli
nmem --version
nmem config client set url https://your-server
nmem config client set api-key your-key
```
## Install The Package [#install-the-package]
Install the package in Kimi Code:
```text
/plugins install https://github.com/nowledge-co/community
/plugins enable nowledge-mem
/reload
```
The community repo has a root `kimi.plugin.json` shim for Kimi Code, so the GitHub install path loads the Kimi package directly. Kimi downloads the repository zip for this install; it does not clone submodules. The package includes a session-start skill and a local MCP server for the desktop app at `http://127.0.0.1:14242/mcp/`.
It also includes native plugin hooks for `Stop`, `SessionEnd`, `PreCompact`, `SubagentStop`, and `Interrupt`, plus quick commands:
```text
/nowledge-mem:status
/nowledge-mem:sync-now
/nowledge-mem:import-history
```
For remote Mem or authenticated localhost, generate a user-level Kimi MCP block:
```bash
nmem config mcp show --host kimi-code
```
Paste the generated `nowledge-mem` server into `$KIMI_CODE_HOME/mcp.json` or `~/.kimi-code/mcp.json`.
If your installed `nmem` does not recognize `--host kimi-code` yet, update the same CLI source first. Until then, use the generic streamable HTTP MCP block from the [Connectors overview](/docs/integrations#direct-mcp) and set the URL/API key for your Mem server manually.
## Thread Sync [#thread-sync]
Modern Kimi Code reads the Nowledge Mem hook declarations from the plugin manifest. After `/reload`, the connector syncs sessions automatically when a turn stops, a session exits, context is compacted, a subagent finishes, or a turn is interrupted.
If you are on an older Kimi Code build that does not load plugin manifest hooks, run the fallback installer once. It writes the same hook rules into your Kimi Code config and leaves the rest of the file untouched:
```bash
python3 ~/.cache/nowledge-community/nowledge-mem-kimi-code-plugin/scripts/install_hooks.py
```
## Verify [#verify]
Restart Kimi Code and ask:
```text
Is Nowledge Mem connected? Read my current context.
```
Success means Kimi Code can call the Nowledge Mem MCP tools and return Context Bundle, Working Memory, or an empty-but-successful memory result.
Then finish a short Kimi Code exchange and check:
```bash
nmem t list --source kimi-code -n 5
```
You should see the recent Kimi Code thread after the hook has run. If you delegated work to a Kimi subagent, that subagent's wire log is imported into the same thread with subagent provenance metadata.
## Import Older Sessions [#import-older-sessions]
Kimi Code stores local sessions under `~/.kimi-code/sessions`. Import them with:
```bash
nmem t sync --from kimi-code --limit 20
nmem t sync --from kimi-code --apply
```
This works for local Mem and remote Mem because the `nmem` CLI reads the local Kimi Code transcript files and uploads normalized thread messages to your configured Mem server. It is safe to rerun; Mem uses stable thread and message IDs to deduplicate repeated imports.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [OpenCode](/docs/integrations/opencode) · [Pi](/docs/integrations/pi) · [ZCode](/docs/integrations/zcode)
* Kimi Code source: [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code)
# Kimi Work × Nowledge Mem (/docs/integrations/kimi-work)
Paste this into Kimi Work:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Kimi Work. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Kimi Work can use Nowledge Mem through the Kimi Work connector. It installs a session-start skill and local MCP declaration into Kimi Work's embedded Kimi Code runtime, which is separate from any Kimi Code CLI you installed yourself.
Kimi Work does not expose lifecycle hooks today. That means Mem can give Kimi Work context and memory tools, but conversation import is explicit: preview and run `nmem t sync --from kimi-work --apply` when you want Kimi Work history in Mem Threads.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* Kimi Work Desktop is installed
* `nmem` 0.9.23 or newer works on the same machine as Kimi Work
```bash
nmem status
nmem --version
```
If Kimi Work runs on a different machine from the desktop app, install the standalone CLI there first:
```bash
python3 -m pip install --user nmem-cli
nmem --version
nmem config client set url https://your-server
nmem config client set api-key your-key
```
## Install The Connector [#install-the-connector]
Get the community checkout if you do not already have it:
```bash
git clone --depth 1 https://github.com/nowledge-co/community.git ~/.cache/nowledge-community
```
Install into Kimi Work's embedded runtime:
```bash
python3 ~/.cache/nowledge-community/nowledge-mem-kimi-work-connector/scripts/install_kimi_work_plugin.py
```
The installer uses `KIMI_WORK_HOME` when set. Otherwise it uses the default macOS Kimi Work runtime path:
```text
~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/home
```
Restart Kimi Work after installing.
## Remote Mem Or Authenticated Localhost [#remote-mem-or-authenticated-localhost]
The connector bundles a local MCP server for the desktop app at `http://127.0.0.1:14242/mcp/`.
For remote Mem or authenticated localhost, generate a Kimi Work MCP block:
```bash
nmem config mcp show --host kimi-work
```
Paste the generated `nowledge-mem` server into `$KIMI_WORK_HOME/mcp.json`, or into the default runtime path shown above plus `/mcp.json`.
Restart Kimi Work after changing MCP config.
## Verify [#verify]
Start a new Kimi Work session and ask:
```text
Is Nowledge Mem connected? Read my current context.
```
Success means Kimi Work can call the Nowledge Mem MCP tools and return Context Bundle, Working Memory, or an empty-but-successful memory result.
## Import Kimi Work Sessions [#import-kimi-work-sessions]
Preview first:
```bash
nmem t sync --from kimi-work --limit 20
```
Import when the preview looks right:
```bash
nmem t sync --from kimi-work --apply
nmem t list --source kimi-work -n 5
```
This works for local Mem and remote Mem because the `nmem` CLI reads Kimi Work's local transcript files and uploads normalized thread messages to your configured Mem server. It is safe to rerun; Mem uses stable thread and message IDs to deduplicate repeated imports.
If Kimi Work stores sessions somewhere else, pass the runtime sessions folder explicitly:
```bash
nmem t sync --from kimi-work --session-dir "/path/to/kimi-work/home/sessions" --apply
```
## Kimi Work vs Kimi Code [#kimi-work-vs-kimi-code]
Kimi Code CLI and Kimi Work share the same underlying Kimi Code session format, but they do not share the same home directory.
* Use [Kimi Code](/docs/integrations/kimi-code) when you run the terminal or IDE coding agent. It supports a hook installer for automatic local thread sync.
* Use this Kimi Work guide for Kimi Work Desktop. It has MCP and startup guidance, but no lifecycle hook, so thread import is explicit.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Import existing conversations](/docs/import-existing-conversations)
* [Kimi Code](/docs/integrations/kimi-code)
# Lody (/docs/integrations/lody)
Lody runs local sessions through an Agent Config. That config chooses an AI tool, such as Claude Code or Codex, and can carry environment variables into it.
This is not the same as an always-on teammate identity. Treat Lody as a session and runtime launcher first. Add a Mem AI Identity only when you intentionally use one Lody Agent Config as a stable role, such as "reviewer" or "onboarding assistant".
Use this rule:
* First connect the AI tool Lody launches, such as Claude Code or Codex.
* Add `NMEM_AGENT_ID` only when this Lody Agent Config represents a stable role, such as Cindy.
* Leave `NMEM_AGENT_ID` unset for generic runtime presets.
## Setup [#setup]
First connect the AI tool Lody launches. For example, install the [Claude Code](/docs/integrations/claude-code) or [Codex](/docs/integrations/codex-cli) connector.
If this Agent Config is meant to represent a durable role, create the Mem AI Identity:
```bash
nmem agents upsert cindy \
--name "Cindy" \
--default-space onboarding \
--instructions "Help with onboarding. Explain one step at a time."
```
This creates the Mem AI Identity named Cindy. Its command and environment ID is `cindy`. It does not make every Codex session use Cindy; the identity is used only where `NMEM_AGENT_ID=cindy` or `agent_id="cindy"` is passed.
Add this environment variable to that Lody Agent Config:
```bash
NMEM_AGENT_ID=cindy
```
If the Lody config is only a generic Codex or Claude runtime preset, leave `NMEM_AGENT_ID` unset. That avoids pretending every Lody session is the same long-term person.
If you create another Lody config for the same durable role, keep the same `NMEM_AGENT_ID`. If the config switches from Codex to Claude Code, update the runtime connector and `--source-app`, not the identity.
## Space [#space]
Do not set `NMEM_SPACE` by default. Use the identity's default space unless this entire Lody config should always read and write one specific Mem space:
```bash
NMEM_SPACE=onboarding
```
## Advanced Host Ids [#advanced-host-ids]
Most users should not set `NMEM_HOST_AGENT_ID`.
Use it only when you need to map a Lody-internal stable id, such as `lody:`, onto a Mem AI Identity. In normal setup, either leave identity unset or use `NMEM_AGENT_ID=cindy` for a role-specific config.
## Forking [#forking]
If the same person should behave differently, create a new Mem AI Identity instead of overloading one identity:
```bash
nmem agents upsert cindy-reviewer \
--name "Cindy Reviewer" \
--instructions "Review code. Leave concise comments. Do not edit files unless asked."
```
Then point that Lody config at:
```bash
NMEM_AGENT_ID=cindy-reviewer
```
## Next [#next]
* [Customize Connector Behavior](/docs/integrations/customize-behavior)
* [Raft](/docs/integrations/raft)
* [Multica](/docs/integrations/multica)
# MiMo Code × Nowledge Mem (/docs/integrations/mimo-code)
Paste this into MiMo Code:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for MiMo Code. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
MiMo Code is OpenCode-derived, but its package names, config roots, and lifecycle APIs are not identical. Use the MCP path for live memory tools, and use `nmem t sync --from mimo-code` when you want MiMo Code's local transcripts imported into Mem.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* MiMo Code is installed
* `nmem` works on the same machine as MiMo Code
```bash
nmem status
```
## Setup [#setup]
Generate the MCP config:
```bash
nmem config mcp show --host mimo-code
```
Add the generated MCP server to MiMo Code's MCP configuration or project config. Then add Nowledge Mem guidance to your project instructions so the agent knows when to read context, search memory, and save durable decisions.
## Verify [#verify]
Restart MiMo Code and ask:
```text
Is Nowledge Mem connected? Search my memory for this project.
```
Success means MiMo Code can call the Nowledge Mem MCP tools and return results or a clean empty result.
## Session Capture [#session-capture]
MiMo Code stores local conversation data in its `mimocode.db` store. Import it with:
```bash
nmem t sync --from mimo-code --limit 20
nmem t sync --from mimo-code --apply
```
This works for local Mem and remote Mem because `nmem` reads the local MiMo Code database and uploads normalized thread messages to your configured Mem server.
Do not install the OpenCode plugin package into MiMo Code unless you are intentionally testing compatibility. The two hosts are close, but a safe live connector must respect MiMo Code's own plugin and session contracts. Until a native package ships, use this import path plus handoff summaries for conversations you want to preserve immediately.
## Related [#related]
* [OpenCode](/docs/integrations/opencode)
* [Kimi Code](/docs/integrations/kimi-code) · [ZCode](/docs/integrations/zcode) · [OMP](/docs/integrations/omp)
* MiMo Code source: [XiaomiMiMo/MiMo-Code](https://github.com/XiaomiMiMo/MiMo-Code)
# Multica (/docs/integrations/multica)
Multica runs named agents by starting local AI tools such as Claude Code, Codex, Pi, OpenCode, or OpenClaw. Connect Nowledge Mem at that launched-tool layer, then give each durable Multica agent one Mem AI Identity.
This means:
* Sessions inside the launched AI tool can sync through that tool's Nowledge Mem connector and hooks.
* MCP access must be configured for the Multica agent, not only for the outer terminal you are using.
* The Multica agent keeps the same Mem AI Identity when you move it to another workspace or switch the AI tool it uses.
* Multica's own workspace history is separate unless Multica exposes an export, API, or hook for it.
## Setup [#setup]
First connect the AI tool Multica launches. For example, install the [Codex](/docs/integrations/codex-cli), [Claude Code](/docs/integrations/claude-code), [Pi](/docs/integrations/pi), or [OpenClaw](/docs/integrations/openclaw) connector on the machine running the Multica daemon.
If the Multica agent runs Claude Code, also open that Multica agent's **MCP** settings and save the Nowledge Mem MCP config there. Claude Code does not automatically inherit MCP servers from your outer shell or another Claude session when Multica starts it. Multica forwards the saved agent MCP config to Claude Code with `--mcp-config`.
Use the same MCP config you would give Claude Code directly:
```json
{
"mcpServers": {
"nowledge-mem": {
"url": "http://127.0.0.1:14242/mcp/",
"type": "streamableHttp",
"headers": {
"APP": "Claude Code",
"Authorization": "Bearer ",
"X-NMEM-API-Key": ""
}
}
}
}
```
You can generate the exact config for your machine with:
```bash
nmem config mcp show --host claude-code --json
```
For remote Mem, replace the URL with your Access Anywhere MCP endpoint and keep the token headers from your Mem config. Do not put `--mcp-config` in Multica custom args; current Multica owns that flag and derives it from the agent's MCP config.
Create the Mem AI Identity:
```bash
nmem agents upsert cindy \
--name "Cindy" \
--default-space onboarding \
--instructions "Help with onboarding. Explain one step at a time."
```
This creates the Mem AI Identity named Cindy. Its command and environment ID is `cindy`. It does not make every Codex session use Cindy; the identity is used only where `NMEM_AGENT_ID=cindy` or `agent_id="cindy"` is passed.
Then add this custom environment variable to the Multica agent:
```bash
NMEM_AGENT_ID=cindy
```
Keep Cindy's ID if she moves to another Multica workspace, squad, or AI tool. Change the connector only when the underlying AI tool changes.
## What Syncs [#what-syncs]
New sessions sync only when the launched AI tool has a working Nowledge Mem connector or hook. For example, Claude Code and Codex use their own Nowledge Mem connectors; Pi uses the Pi package; OMP uses the OMP plugin.
Multica itself is the orchestrator. Its issue comments, workspace history, and task timeline are separate data. Mem can import those directly only if Multica later exposes message-level export, API, or hook data for those surfaces.
## Space [#space]
Leave `NMEM_SPACE` unset unless every task assigned to this Multica agent should use one Mem space:
```bash
NMEM_SPACE=onboarding
```
If the agent works across multiple repos or projects, let the Mem AI Identity's default space handle the usual case and switch space explicitly only when needed.
## Security [#security]
Do not put broad secrets in Multica agent environment variables. `NMEM_AGENT_ID` is safe because it is only an identity selector. Mem API keys, provider keys, and production tokens should stay limited in scope and managed through the runtime or Mem client config.
## Next [#next]
* [Customize Connector Behavior](/docs/integrations/customize-behavior)
* [Lody](/docs/integrations/lody)
* [Cumora](/docs/integrations/cumora)
# OMP × Nowledge Mem (/docs/integrations/omp)
Paste this into OMP:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for OMP. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
Install the OMP plugin when you want OMP to start with the right Mem context and save new coding conversations without a manual import step.
After setup, OMP can read Context Bundle or Working Memory at startup, use the bundled memory skills during a task, and sync completed conversation turns into Mem threads with `source_app=omp`.
Do not install `nowledge-mem-pi` for OMP. OMP is Pi-derived, but it has its own plugin command, config root, and source tag. The dedicated OMP plugin keeps OMP threads separate from Pi threads.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* OMP is installed
* `nmem` works on the same machine as OMP
```bash
nmem status
```
## Setup [#setup]
```bash
omp plugin install nowledge-mem-omp
```
Restart OMP after install or update so the extension lifecycle loads.
For most local setups, that is the only OMP-specific install step.
If you also want direct MCP tool calls, or need to point OMP at a custom remote MCP endpoint, generate the optional OMP MCP config:
```bash
nmem config mcp show --host omp
```
Add the generated server to OMP's MCP config. OMP's documented MCP locations include project `.omp/mcp.json` and user `~/.omp/agent/mcp.json`.
## Verify [#verify]
Restart OMP and ask:
```text
Read my Nowledge Mem context and tell me whether the connection is working.
```
Success means OMP can see the injected Context Bundle or Working Memory. After you complete a normal OMP turn, the conversation should also appear in Mem as an OMP thread.
## Session Capture [#session-capture]
New OMP conversations are captured automatically by the plugin after completed agent turns, before compaction, before session switches, and at shutdown. They are saved with `source_app=omp`.
Only use the sync command when you want to backfill older OMP sessions that existed before the plugin was installed. OMP stores those sessions under `~/.omp/agent/sessions`:
```bash
nmem t sync --from omp --limit 20
nmem t sync --from omp --apply
```
This works for local Mem and remote Mem because `nmem` reads the local OMP JSONL files on the OMP machine and uploads normalized thread messages to your configured Mem server.
## Related [#related]
* [Pi](/docs/integrations/pi)
* [OpenCode](/docs/integrations/opencode) · [Kimi Code](/docs/integrations/kimi-code) · [ZCode](/docs/integrations/zcode)
* OMP docs: [omp.sh/docs](https://omp.sh/docs)
# OpenClaw × Nowledge Mem (/docs/integrations/openclaw)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for OpenClaw. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="One-liner install"
openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem
```
Configure the plugin and the conversations you have with OpenClaw land in Mem as searchable threads. Background cron-style runs do not. Mem can still distill what matters into linked memories, and what you saved in other tools, documents, or imports stays available to the agent. Local-first by default; add `apiUrl` and an optional `apiKey` if you use a shared server.
Behind that, Nowledge Mem is doing more than storing notes. It links related knowledge into a graph, tracks how ideas evolve, and can keep processing in the background so OpenClaw can benefit from daily briefings, contradiction checks, and crystals built from multiple sources.
The fastest proof is simple: remember one fact, recall it in a fresh session, then confirm the session itself shows up as a searchable thread.
The package is now published on ClawHub. Use the explicit `clawhub:` install form when you want to make the source clear. Bare package names still work because OpenClaw resolves ClawHub before npm.
## Before You Start [#before-you-start]
You need:
* **Nowledge Mem** running locally ([installation](/docs/installation))
* **OpenClaw 2026.5.3 or later** ([OpenClaw getting started](https://docs.openclaw.ai/start/openclaw)). Older 2026.4.x builds can reject current ClawHub packages with an archive integrity mismatch before the plugin is installed.
* **`nmem` CLI** on your PATH. In Nowledge Mem, go to **Settings → Preferences → Developer Tools → Install CLI**. Or install standalone: `pip install nmem-cli`
```bash
nmem status # should show Nowledge Mem is running
openclaw --version
```
## Setup [#setup]
### Install the plugin [#install-the-plugin-step]
```bash
openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem
```
The installer enables the plugin and switches OpenClaw's `memory` slot to `openclaw-nowledge-mem` automatically. On current OpenClaw builds, that same install flow may also set `plugins.slots.contextEngine` to `openclaw-nowledge-mem`. Plugin `0.8.18+` accepts that automatically as a compatibility alias.
Current OpenClaw releases require an explicit grant before a non-bundled plugin can read the `agent_end` conversation used as the thread-sync safety net:
```bash
openclaw config set plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess true --strict-json
```
Next, run `openclaw config get tools`. If you use a restrictive profile such as `coding`, preserve any existing `tools.alsoAllow` entries and add `openclaw-nowledge-mem`. If `tools.allow` already exists, add the plugin id to that list instead. Do not replace an existing list or enumerate individual `nowledge_mem_*` tools; the plugin id grants the complete manifest-declared contract.
If an earlier ClawHub install was blocked with `dangerous code patterns detected`,
update to `0.8.17+`. That release removes test-only files from the published
plugin artifact, so OpenClaw only scans real runtime code during install.
If you prefer the default resolver path, this also works:
```bash
openclaw plugins install @nowledge/openclaw-nowledge-mem
```
To update to the latest version:
```bash
openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem --force
```
This refreshes the plugin from ClawHub and replaces the installed copy. Use it
instead of `openclaw plugins update openclaw-nowledge-mem` if your local
OpenClaw install was previously pinned to a specific plugin version.
If OpenClaw reports `archive integrity mismatch` during install, update
OpenClaw first, then run the same `--force` install command again.
## Customize Safely [#customize-safely]
OpenClaw does not use a separate project instruction file for this plugin.
* Use the plugin settings and OpenClaw config for durable behavior changes
* Use your agent or prompt configuration when you want different memory style, language, or recall policy
* Do not patch installed plugin source under `~/.openclaw/extensions/`
For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
### Pin trust for non-bundled plugins (recommended) [#pin-trust-for-non-bundled-plugins-recommended-step]
If OpenClaw warns that `plugins.allow` is empty, add this:
```json
{
"plugins": {
"allow": ["openclaw-nowledge-mem"]
}
}
```
If you also use linked or workspace copies, review `plugins.load.paths` too. OpenClaw allowlists plugin ids, not install provenance.
### Restart OpenClaw and verify [#restart-openclaw-and-verify-step]
```bash
openclaw nowledge-mem status
```
If Nowledge Mem is reachable, you're done.
If you manage OpenClaw config manually instead of using `openclaw plugins install`, make sure `plugins.slots.memory` is `openclaw-nowledge-mem` and `plugins.entries.openclaw-nowledge-mem.enabled` is `true`.
For local mode, no API key is needed. If you are connecting to a remote Nowledge Mem server instead, set `apiUrl`, and add `apiKey` when that server has auth enabled.
## Spaces [#spaces]
OpenClaw can keep one ambient memory lane per profile or process.
* Use `NMEM_SPACE="Research Agent"` when one OpenClaw process already belongs to one lane.
* Or set plugin config `space` for one fixed lane in the OpenClaw UI.
* Use `spaceTemplate` only when your launcher already exports a trustworthy lane variable such as `${OPENCLAW_AGENT_NAME}`.
If the runtime does not expose agent identity cleanly, do not fake per-agent mapping. Use one profile per lane or stay on **Default**.
## Verify It Works (1 Minute) [#verify-it-works-1-minute]
In OpenClaw chat:
1. `/remember We chose PostgreSQL for task events`
2. `/recall PostgreSQL`: should find it immediately
3. `/new`: start a fresh session
4. Ask: `What database did we choose for task events?`: it remembers across sessions
5. Ask: `What was I working on this week?`: weekly activity view
6. Ask: `What was I doing on February 17?`: down to the exact day
7. `/forget PostgreSQL task events`: clean deletion
If all seven steps work, the memory system is fully running.
## What You Can Do [#what-you-can-do]
**Your chats stay. Automation does not.**
Talk in OpenClaw and those turns save as threads you can search later. The plugin skips automation sessions such as `cron-worker`, so the list stays readable. When something in a session is worth keeping, Mem can distill it into structured memories and point back to the chat with `sourceThreadId`.
**Use graph-based memory, not a flat archive**
Memories are linked to related entities, earlier and later versions of the same idea, and the source conversations they came from. That means OpenClaw can do more than keyword recall. It can trace how a decision changed, follow connected topics, and explain where an answer came from.
**Let knowledge improve in the background**
When Background Intelligence is enabled in Nowledge Mem, the system keeps working after the session ends: deduplicating overlap, surfacing contradictions, writing Working Memory briefings, and creating crystals when several memories converge into something worth keeping. OpenClaw can read those outputs the next time you work.
**Remember anything, forever**
Tell the AI `/remember We decided against microservices, the team is too small`. Next week, in a different session, ask "what was that decision about microservices?" It finds it.
**Browse your work by date**
Ask "what was I doing last Tuesday?" and the AI lists everything you saved, documents you added, and insights generated that day. You can ask for a specific date, not just "the past N days."
**Bring the rest of your AI work into OpenClaw**
What you learned in Claude, decided in Cursor, captured from browser chats, or imported from past threads can all become part of the same memory layer. OpenClaw is not an island. It is one connected path in a larger system.
**Trace a decision's history**
Ask the AI "how did this idea develop?" and it shows you: the original source documents that informed it, which related memories were synthesized into a higher-level insight, and how your understanding changed over time.
**Optional: start every session already in context**
If you enable `sessionContext`, Context Bundle / Working Memory and relevant memories are injected before the first response. That gives OpenClaw immediate context from turn one. In the default mode, the agent still gets memory tools and a short system hint, but it decides when to search.
**Save knowledge with structure, not just text**
When you ask the AI to remember something, it doesn't just store text. It records the type (decision, learning, preference, plan...), when it happened, and links it to related knowledge. Searching by type, by date, by topic all work because the structure is there.
**Trace a memory to its source conversation**
When a memory was distilled from a conversation, it includes a `sourceThreadId`. The agent can fetch the full conversation with `nowledge_mem_thread_fetch` to see the complete context: what was said, what was decided, and how the conclusion was reached.
**Search past conversations directly**
Ask "find the conversation where we discussed Redis caching" and the agent uses `nowledge_mem_thread_search` to find matching threads with message snippets. Then fetch full messages with `nowledge_mem_thread_fetch` for progressive retrieval of long conversations.
**Slash commands**: `/remember`, `/recall`, `/forget`
## How It Works [#how-it-works]
### Per-turn flow [#per-turn-flow]
Every time you send a message, the plugin injects behavioral guidance before the agent processes it. The agent then decides which tools to call.
The behavioral skill and always-on hook nudge the agent to **search before answering** and **save after deciding**. Here's when each tool fires:
| Scenario | Tool | What happens |
| ------------------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------- |
| User asks a question | `memory_search` | Search knowledge base before answering. Returns `sourceThreadId` when available. |
| Decision made, insight learned | `nowledge_mem_save` | Structured save: type + labels + temporal context. |
| "What was I doing last week?" | `nowledge_mem_timeline` | Activity feed grouped by day. Supports exact date ranges. |
| "How is X connected to Y?" | `nowledge_mem_connections` | Graph walk: edges, entities, EVOLVES chains, provenance. |
| Need startup context or today's focus/priorities | `nowledge_mem_context` | Read Context Bundle when available, with Working Memory fallback. |
| Memory has `sourceThreadId` | `nowledge_mem_thread_fetch` | Fetch full source conversation with pagination. |
| "Find our discussion about X" | `nowledge_mem_thread_search` | Search past conversations by keyword. |
| "Forget X" | `nowledge_mem_forget` | Delete by ID or search query. |
| "Is my setup working?" | `nowledge_mem_status` | Show config, connectivity, and version. |
### Session lifecycle (automatic capture) [#session-lifecycle-automatic-capture]
When sessions end, conversations are automatically captured and optionally distilled into structured memories.
Key points:
* Sessions where you are really chatting in OpenClaw are saved automatically. They show up in Mem like threads from other assistants.
* Isolated cron or other automation sessions are not captured. OpenClaw gives them separate keys; you might notice `cron-worker` in diagnostics. Leaving them out of Threads is deliberate.
* Distillation runs when the transcript grows on a normal path (`agent_end`, or each Context Engine turn). A compaction-only checkpoint does not, by itself, trigger a new distill pass.
* If you enable the Context Engine, prompt assembly moves there, but thread capture still keeps the lifecycle hooks as a backstop. That makes session sync more resilient without creating duplicate threads.
* Distilled memories include `sourceThreadId` so you can open the source conversation.
### Progressive retrieval (memory to thread to messages) [#progressive-retrieval-memory-to-thread-to-messages]
Memories distilled from conversations carry a `sourceThreadId`. This creates a chain: search memories, trace to source conversation, read full messages with pagination.
Two entry points into past conversations:
1. **From a memory**: `memory_search` or `memory_get` returns `sourceThreadId`, then fetch the source conversation
2. **Direct search**: `nowledge_mem_thread_search` finds conversations by keyword, then fetch any match
### Three modes [#three-modes]
The plugin supports three operating modes. Choose based on how much you want to guarantee versus how much token budget you're willing to spend.
| Mode | Config | Behavior | Token cost |
| ------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Default** (recommended) | `sessionContext: false` | Agent calls 10 tools on demand. Conversations captured + distilled at session end. | Lowest overhead. The agent decides when to search. |
| **Session context** | `sessionContext: true` | Context Bundle / Working Memory + relevant memories injected at prompt time, plus all 10 tools still available. | Higher per-turn context cost, but context is present from turn one. |
| **Minimal** | `sessionDigest: false` | Tool-only, no automatic capture. | Small overhead from the always-on system hint only. |
**Which mode should you use?**
* **Most users**: start with default. The agent gets behavioral guidance nudging it to search before answering and save after deciding. It works well for most conversations.
* **Short sessions or critical accuracy**: enable `sessionContext`. This guarantees relevant memories are present from the first turn. The agent doesn't need to decide whether to search. The tradeoff is a larger prompt on each turn.
* **Full manual control**: set `sessionDigest: false`. You control what gets saved (via `/remember` or `nowledge_mem_save`) and nothing is captured automatically.
### sessionContext - Automatic context injection [#sessioncontext---automatic-context-injection]
When enabled, the plugin injects context at prompt time:
1. Reads **Context Bundle** when available: owner identity, agent identity, active space, Rules, Working Memory, and KFS paths. Older `nmem` clients fall back to Working Memory.
2. Searches your knowledge graph for **memories relevant to your current prompt**
3. Appends the recalled material as run-specific context in system-prompt space, so the stable prefix stays cached and token costs stay low
The behavioral guidance automatically adjusts when `sessionContext` is on. It tells the agent that context has already been injected, so `memory_search` should only be used for specific follow-up queries, not broad recall. This prevents redundant searches for the same context.
Useful for giving the agent immediate context without waiting for it to search proactively. Best for short sessions and critical workflows where you want guaranteed recall.
### sessionDigest - Thread capture + LLM distillation (default: on) [#sessiondigest---thread-capture--llm-distillation-default-on]
On by default. Two things happen at session lifecycle events (`agent_end`, `after_compaction`, `before_reset`):
**1. Thread capture (interactive sessions).** The full chat is appended to a Mem thread and stays searchable with `nowledge_mem_thread_search`. Cron and other isolated automation use different session keys; the plugin skips them so scheduled runs do not sit next to the conversations you started yourself.
**2. LLM distillation (when worthwhile).** After thread capture, a lightweight LLM triage determines if the conversation contains save-worthy content (decisions, insights, preferences). If yes, a full distillation pass extracts structured memories with proper types, labels, and temporal data. Works in **any language**.
**Context compaction**: when OpenClaw compresses a long conversation, the plugin captures the transcript first. Nothing is lost.
**Deduplication**: thread appends are idempotent by message ID. No duplicates.
## Common Questions [#common-questions]
**Does the agent always search before answering?**
The plugin uses two layers to drive recall. First, a behavioral skill (auto-discovered by OpenClaw) teaches the agent when and how to use memory tools. Second, a short always-on system hint reminds it to search before answering questions about prior work, decisions, or preferences. In practice, modern LLMs follow this directive guidance reliably for knowledge-related questions. For messages that don't need past context, the agent skips the search, which is the right tradeoff. If guaranteed recall matters for your use case, enable `sessionContext: true`. That injects relevant memories at prompt time, before the agent processes your message.
**What stops the agent from saving the same thing twice?**
Two layers. First, the plugin checks for near-identical existing memories before every save. If a memory with very high similarity already exists, the save is skipped and the existing memory is returned instead. Second, Nowledge Mem's Background Intelligence runs in the background and handles deeper deduplication, identifying semantic overlap across memories and linking them via EVOLVES chains (replaces, enriches, confirms, or challenges). The plugin catches obvious duplicates; Background Intelligence catches subtle ones.
**What happens to conversations I don't explicitly save?**
With `sessionDigest` on (the default), chats you have in OpenClaw are stored as searchable threads. The boundary follows OpenClaw's own session lifecycle: one active chat becomes one Mem thread, `/new` or `/reset` starts a fresh thread, and transcript rotation during compaction stays inside the same thread. Context Engine capture and hook-based capture still converge on the same conversation. Helper sessions such as `temp:*` and subagent runs are filtered out, so your recent threads stay focused on real chats. Find them later with `nowledge_mem_thread_search`. A small LLM pass may promote a rich session into structured memories; casual small talk usually stops at the thread. Cron runs never enter this path.
**Can memories become outdated?**
Yes, and that's by design. Nowledge Mem's EVOLVES chains track how understanding changes: a newer memory can supersede, enrich, or challenge an older one. Background Intelligence identifies these relationships automatically. When you search, the relevance scoring considers recency, so newer memories rank higher by default.
## Configuration [#configuration]
No config is needed for a normal npm install. The installer already enables the plugin and selects the memory slot.
To change settings, open the OpenClaw dashboard and go to **Automation > Plugins**. Under **Plugin Entries**, expand **Nowledge Mem**, then **Nowledge Mem Config**. You can also type "nowledge" in the search bar to jump straight there.
Changes take effect after restarting OpenClaw.
| Setting | Default | What it does |
| ------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session context injection | off | Inject Context Bundle / Working Memory + relevant memories at prompt time |
| Session digest at end | on | Capture conversations + distill key memories at session end |
| Minimum digest interval | 300s | Seconds between session digests (0 = no limit) |
| Max context results | 5 | Memories to inject at prompt time (1-20) |
| Min recall score | 0 | Only inject memories scoring above this threshold (0-100%). 0 includes all results. |
| Max thread message chars | 800 | Characters kept per captured thread message (200-20000). Raise for long code or technical conversations. |
| Corpus supplement | off | Feed your knowledge into OpenClaw's dreaming system (see below) |
| Corpus max results | 5 | Max results per dreaming search (1-20) |
| Corpus min score | 0 | Min score for dreaming results (0-100%). 0 includes all. |
| Dreaming | managed by OpenClaw | Optional OpenClaw dreaming settings. When Nowledge Mem owns the memory slot, OpenClaw may store its native `dreaming` object here. `memory-core` still runs the dreaming engine. |
| Server URL | empty | Remote server URL (empty = local) |
| API key | empty | API key for remote access |
### Remote access [#remote-access]
To connect to a Nowledge Mem server on another machine, configure this machine once:
```bash
nmem config client set url https://
nmem config client set api-key nmem_...
```
That writes the shared local client config used by `nmem`, OpenClaw, Bub, Claude Code, and other integrations on this machine. You can also set **Server URL** and **API key** in the OpenClaw dashboard plugin settings. The same resolved credentials are used everywhere in the plugin: CLI-backed memory tools and API-backed thread sync both follow the same `apiUrl` and `apiKey`. The API key never appears in logs or command history. See [Access Mem Anywhere](/docs/remote-access).
## Troubleshooting [#troubleshooting]
**Plugin is installed but OpenClaw isn't using it**
Check that `plugins.slots.memory` is exactly `openclaw-nowledge-mem`, and that you restarted OpenClaw after editing the config.
**`plugins.allow is empty` warning**
This means OpenClaw found a non-bundled plugin without an explicit allowlist entry yet. If this is your npm-installed plugin, add:
```json
{
"plugins": {
"allow": ["openclaw-nowledge-mem"]
}
}
```
If you also use `plugins.load.paths` or linked workspace copies, review those paths too. OpenClaw allowlists ids, not install provenance.
**"Duplicate plugin id detected" warning**
This happens if you previously installed the plugin locally (e.g. with `--link`) and then installed from npm. OpenClaw is loading it from both places. Fix it by removing the local path from your config:
Open `~/.openclaw/openclaw.json` and delete the `plugins.load.paths` entry that points to the local plugin directory:
```json
"load": {
"paths": []
}
```
Then restart OpenClaw. The warning will be gone and only the npm-installed version will load.
**Status shows not responding**
```bash
nmem status
curl -sS http://127.0.0.1:14242/health
```
**Memory tools work, but the session itself does not show up in Threads**
Run `nowledge_mem_status` inside a normal chat session and confirm:
* `sessionDigest` is still on
* the backend is reachable
* which capture route is active
* whether you changed plugin settings recently without restarting OpenClaw yet
If you enabled `plugins.slots.contextEngine: "nowledge-mem"`, plugin `0.8.6+` keeps lifecycle hooks as a safety net for thread sync. On current OpenClaw installer builds, `plugins.slots.contextEngine` may instead be `openclaw-nowledge-mem`; plugin `0.8.18+` treats that as the same engine. On `0.8.5` and earlier, a useful isolation step is to remove the `contextEngine` slot temporarily, restart OpenClaw, and see whether thread capture returns on the hook-only path.
If threads stopped updating right after an OpenClaw upgrade, update the Nowledge Mem plugin and restart OpenClaw. Plugin `0.8.24+` handles newer per-turn capture events from OpenClaw's Codex runtime. Plugin `0.8.27+` is also required for OpenClaw builds that log `must declare contracts.tools before registering agent tools`; that error means OpenClaw rejected the plugin's tools before capture hooks could run.
OpenClaw `2026.6.11` emits numeric message timestamps. Plugin `0.8.30+` converts them to the textual timestamp contract used by Mem Threads. It also reports when OpenClaw is blocking the `agent_end` fallback. Grant access and restart after upgrading:
```bash
openclaw config set plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess true --strict-json
openclaw gateway restart
```
OpenClaw applies plugin setting changes after restart. If `sessionDigest` was turned off earlier but OpenClaw had not restarted yet, thread sync could appear to keep working until the next restart, then stop.
Healthy OpenClaw thread sync looks like this:
* one active OpenClaw chat becomes one Mem thread
* running `/new` or `/reset` starts a fresh Mem thread
* compaction does not fork a second thread for the same chat
* helper sessions like `temp:slug-generator` do not appear
* the synthetic `/new` / `/reset` startup prompt is not saved as the first user message
To inspect the recent synced threads directly:
```bash
nmem t list --source openclaw -n 20
```
**Only `memory_search` and `memory_get` work, saves go to local files**
First run `openclaw config get tools`. If a restrictive profile such as `coding` is active, preserve its policy and add `openclaw-nowledge-mem` to `tools.alsoAllow`; if `tools.allow` already exists, add the plugin id there. Then check the memory slot. OpenClaw 3.22+ defaults the memory slot to `memory-core` when no explicit slot is configured, so a manual install or upgrade can require the slot to be set again.
Verify your config has the explicit slot:
```json
{
"plugins": {
"slots": { "memory": "openclaw-nowledge-mem" }
}
}
```
Or reinstall, which sets the slot automatically:
```bash
openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem
```
Restart OpenClaw after either change.
**Plugin tools not available**
Plugin trust and tool policy are separate gates. Make sure the plugin is in `plugins.allow`:
```json
{
"plugins": {
"allow": ["openclaw-nowledge-mem"]
}
}
```
Then inspect `openclaw config get tools`. A restrictive profile needs `openclaw-nowledge-mem` in `tools.alsoAllow`, unless an explicit `tools.allow` already exists, in which case add the plugin id there. Preserve existing entries. Do not list individual `nowledge_mem_*` names: using the plugin id keeps the granted surface aligned with the manifest.
**Search is slow with many concurrent agents**
When running many agents in parallel (10+), search performance can degrade because all operations share a single database connection. Recommendations:
* Upgrade to Nowledge Mem v0.6.12+ (backend): scoring writes no longer block search responses
* If your agents use the CLI transport, consider setting a remote API URL in the plugin config to reduce subprocess overhead
**Search returns too few results**
Raise `maxContextResults` to `8` or `12`.
## Why Nowledge Mem? [#why-nowledge-mem]
Other memory tools store what you said as text and retrieve it by semantic similarity. Nowledge Mem is different.
**Knowledge has structure.** Every memory knows what type it is (decision, learning, plan, preference), when it happened, which source documents it came from, and how it relates to other memories. That's what makes search precise and reasoning reliable.
**Knowledge evolves.** The understanding you wrote today connects to the updated version you saved three months later. You can see how your thinking changed, without losing the intermediate steps.
**Knowledge has provenance.** Every piece of knowledge extracted from a PDF, document, or web page links back to its source. When the AI says "based on your March design doc," you can verify it.
**Knowledge travels across tools.** What you learned in Cursor, saved in Claude, refined in ChatGPT, all available in OpenClaw. Your knowledge belongs to you, not to any one tool.
**Local first, no cloud required.** Your knowledge lives on your machine. Remote access is available when you need it, not imposed by default.
How search ranking works: [Search & Relevance](/docs/search-relevance).
## Working with memory-core (v0.8.0+) [#working-with-memory-core-v080]
The default setup makes Nowledge Mem the memory slot. You get the full tool surface and all 10 tools. Most users should stay here.
Some users prefer to keep OpenClaw's built-in memory-core as the memory slot. memory-core has `MEMORY.md` management and dreaming (an experimental consolidation system that periodically promotes frequently recalled content into long-term storage).
The plugin supports both paths. When `corpusSupplement` is enabled, memory-core's recall pipeline can search your Nowledge Mem knowledge graph directly. Memories you saved from Claude, Cursor, ChatGPT, or other tools show up in memory-core's search results and feed into dreaming.
Use `0.8.15` or later for this setup. Earlier builds could leave the plugin effectively inactive beside `memory-core`, which made some users patch local source files just to keep supplement mode alive.
### What corpus supplement does [#what-corpus-supplement-does]
When memory-core runs a search, it also queries Nowledge Mem. Results from your knowledge graph appear alongside memory-core's own results, scored and ranked together. This means:
* memory-core's recall includes your cross-tool knowledge
* Dreaming (experimental) can promote frequently recalled Nowledge Mem content into `MEMORY.md`
* Weekly pattern extraction can find connections between your knowledge graph and memory-core's data
### Setup [#setup-1]
Keep the memory slot on memory-core (or leave it unset). Then set `corpusSupplement: true` in the plugin settings, or via environment variable `NMEM_CORPUS_SUPPLEMENT=true`.
The plugin handles deduplication automatically. When Nowledge Mem is the memory slot, it handles recall directly. When memory-core is the memory slot and corpus supplement is on, it feeds into memory-core's pipeline instead. You won't get the same content twice.
If OpenClaw stores a top-level `dreaming` object under the Nowledge Mem plugin entry, that is normal. OpenClaw now writes dreaming settings onto the selected memory-slot owner. The plugin accepts that config so memory-core can continue running the dreaming engine alongside Nowledge Mem.
### How to decide [#how-to-decide]
| Setup | Best for |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Nowledge Mem as memory slot (default) | All 10 tools, structured memory types, thread provenance. One system manages everything. |
| memory-core + corpus supplement | You use memory-core's `MEMORY.md` workflow or want dreaming. Your cross-tool knowledge still feeds in. |
Capture and distillation work the same either way. The difference is which system handles recall and long-term consolidation.
## Context Engine (v0.7.0+) [#context-engine-v070]
Starting with plugin v0.7.0, Nowledge Mem can run as a full **Context Engine** in OpenClaw, not just as prompt hooks. This gives it deeper integration with OpenClaw's lifecycle:
* **Memory-aware compaction**: when OpenClaw compresses a long conversation, key decisions and learnings already saved in your knowledge graph are preserved by reference, not lost in summarization
* **Subagent memory propagation**: when OpenClaw spawns parallel research agents, they inherit your memory context automatically
* **Session bootstrap**: Context Bundle or Working Memory is pre-loaded before the first turn, so context is ready immediately
* **Per-turn capture**: conversations are captured after every turn, not just at session end
To activate, add this to your OpenClaw config:
```json
{
"plugins": {
"slots": {
"memory": "openclaw-nowledge-mem",
"contextEngine": "nowledge-mem"
}
}
}
```
If you don't activate the Context Engine, the existing hook-based setup continues to work exactly as before.
If you do activate it, the Context Engine handles prompt assembly and per-turn capture, while the lifecycle hooks remain as a quiet reliability backstop for thread sync. That split is intentional: it keeps context injection clean without making capture depend on a single runtime path.
## For Advanced Users [#for-advanced-users]
OpenClaw's `MEMORY.md` workspace file still works for workspace context. Memory tool calls are handled by Nowledge Mem, but both can coexist.
The plugin uses one shared connection config across its transport paths. Most memory operations still use `nmem`, while conversation-thread sync talks to the Mem server directly so large sessions travel in a normal request body instead of a giant command-line argument. You still configure the address once, and local and remote mode continue to work the same way from the user's point of view.
## Related [#related]
* [Connectors overview](/docs/integrations): native connectors, reusable packages, MCP, and browser capture
* [Claude Code](/docs/integrations/claude-code) · [Claude Desktop](/docs/integrations/claude-desktop) · [Codex](/docs/integrations/codex-cli) · [Alma](/docs/integrations/alma) · [Raycast](/docs/integrations/raycast) · [Other Chat AI](/docs/integrations/other-chat-ai)
## References [#references]
* Plugin source: [nowledge-mem-openclaw-plugin](https://github.com/nowledge-co/community/tree/main/nowledge-mem-openclaw-plugin)
* OpenClaw docs: [Plugin system](https://docs.openclaw.ai/tools/plugin)
* Changelog: [CHANGELOG.md](https://github.com/nowledge-co/community/blob/main/nowledge-mem-openclaw-plugin/CHANGELOG.md)
# OpenCode × Nowledge Mem (/docs/integrations/opencode)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for OpenCode. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="Install"
opencode plugin opencode-nowledge-mem -g
```
OpenCode is a terminal coding agent. Nowledge Mem adds the layer above: knowledge from all your other AI tools, decisions made in Claude Code, preferences set in Cursor, insights from ChatGPT, searchable inside OpenCode. New OpenCode sessions are also captured after OpenCode goes idle, so what you learn there can feed later recall and crystallization without switching tools.
## Before You Start [#before-you-start]
* **Nowledge Mem** running locally ([installation](/docs/installation)) or a reachable remote Mem server
* **OpenCode** installed
* **`nmem` CLI** in your PATH. In Nowledge Mem go to **Settings → Preferences → Developer Tools → Install CLI**, or `pip install nmem-cli`
```bash
nmem status # Nowledge Mem is running
opencode --version # OpenCode is available
```
## Setup [#setup]
### Install the plugin [#install-the-plugin-step]
Install the npm plugin and let OpenCode update your config:
```bash
opencode plugin opencode-nowledge-mem -g
```
Use `-g` for global use across all projects. Omit it when you only want the plugin in the current project.
If you prefer editing config manually, add the plugin name yourself:
```json title="~/.config/opencode/opencode.json"
{
"plugin": ["opencode-nowledge-mem"]
}
```
### Restart OpenCode [#restart-opencode-step]
Close and reopen OpenCode so it loads the plugin.
### Verify the integration [#verify-the-integration-step]
Ask OpenCode to check your Nowledge Mem connection:
```
What was I working on recently?
```
You should see OpenCode call `nowledge_mem_context_bundle` when full startup context matters, or `nowledge_mem_working_memory` as the lightweight fallback, then return your current context. That's success: OpenCode can now see knowledge from your other tools.
To verify thread capture, finish a short turn and wait a moment after OpenCode becomes idle. In another terminal, search for a phrase from the turn:
```bash
nmem t search "the phrase you just used" --source opencode
```
You should see an `opencode-...` thread. If you do not, update the plugin and restart OpenCode so the event hook is loaded.
## Update [#update]
Refresh the global plugin package and replace the installed copy:
```bash
opencode plugin opencode-nowledge-mem -g --force
```
## Customize Safely [#customize-safely]
Use OpenCode's own instruction surfaces, not the installed plugin files:
* `AGENTS.md` in the repo when this project needs shared behavior
* `~/.config/opencode/AGENTS.md` for your personal defaults
* `instructions` in `opencode.json` when you want host-level config instead of file-based guidance
Do not edit the installed Nowledge Mem plugin package directly. For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## What You Can Do [#what-you-can-do]
**Find knowledge from other tools**
Ask "what did we decide about the database?" and OpenCode searches across decisions you made in Claude Code, insights from ChatGPT, notes from Cursor, not just this session.
**Save knowledge for everywhere**
When you reach a conclusion in OpenCode, the agent saves it so your next Claude Code session, Cursor project, or ChatGPT conversation can find it too.
**Start with today's context**
Your Context Bundle, Working Memory briefing, and relevant past knowledge are available before you repeat yourself across tools.
**Keep the full session searchable**
When OpenCode finishes a turn and reports idle, the plugin saves the session as a Mem thread. Long sessions also flush before compaction, so the transcript stays available for search, review, and later knowledge crystallization.
**Create resumable handoffs**
Wrap up in OpenCode, then pick up right where you left off in Claude Code or any other tool. Decisions, plans, and context carry over automatically.
## Tools [#tools]
| Tool | What it does |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `nowledge_mem_context_bundle` | Read startup context: owner identity, agent identity, active space, Rules, Working Memory, and KFS paths. |
| `nowledge_mem_working_memory` | Read today's lightweight Working Memory: focus areas, priorities, recent activity. |
| `nowledge_mem_search` | Search knowledge from all your tools. Supports label, date, and deep mode filters. |
| `nowledge_mem_save` | Save a decision, insight, or preference so any tool can find it. |
| `nowledge_mem_update` | Update an existing memory with refined information. |
| `nowledge_mem_thread_search` | Search past conversations from any tool. |
| `nowledge_mem_save_thread` | Save the current session as a full conversation thread on demand. Automatic idle capture normally handles this for new work. |
| `nowledge_mem_save_handoff` | Save a curated handoff summary (lighter, agent-composed). |
| `nowledge_mem_status` | Check Nowledge Mem server connectivity and diagnostics. |
## How Session Capture Works [#how-session-capture-works]
Nowledge Mem captures OpenCode sessions in four complementary ways:
**Plugin automatic live capture.** When OpenCode reports `session.status=idle` (or the older `session.idle` event), the plugin waits briefly for messages to flush, reads the current session through OpenCode's SDK, and writes the matching `opencode-...` thread to Mem. This is the path you should rely on for new work.
**Pre-compaction flush.** Before OpenCode compacts a long session, the plugin saves the current transcript through the same thread path, then reminds the agent to reload Mem context after compaction.
**Manual full session capture.** `nowledge_mem_save_thread` reads the current session's messages via OpenCode's SDK client and posts them to Nowledge Mem over HTTP. It is safe to run multiple times and remains useful as an explicit fallback.
**Plugin proactive knowledge save.** `nowledge_mem_save` captures individual decisions and insights during the conversation, stamped with `source=opencode`. `nowledge_mem_save_handoff` creates a curated summary at wrap-up. Both complement the full transcript with focused, high-value takeaways.
Desktop import reads OpenCode's local database directly, so it only sees sessions on the machine where Mem is running. In [remote mode](/docs/remote-access), use the native plugin's live capture or run `nmem t sync` on the client machine where OpenCode stores its sessions.
### Import older sessions [#import-older-sessions]
To backfill older OpenCode sessions, preview first:
```bash
nmem t sync --from opencode --all-projects --limit 20
```
Then import:
```bash
nmem t sync --from opencode --all-projects --apply
```
Use `-p /path/to/project` instead of `--all-projects` when you only want one project. The command reads OpenCode's local session database or legacy JSON storage on this machine and writes to the Mem server configured in `nmem`. Imported history becomes searchable immediately; deeper distillation remains an explicit review step.
## Configuration [#configuration]
No config needed for local use.
| Env Variable | Default | What it does |
| -------------- | --------- | ------------------------------ |
| `NMEM_API_URL` | *(local)* | Remote Nowledge Mem server URL |
| `NMEM_API_KEY` | *(none)* | API key for remote access |
For a persistent shared setup, configure this machine once with `nmem config client ...`. Environment variables still take priority when you need a temporary override.
### Remote access [#remote-access]
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
OpenCode uses that same shared config for `nmem` command tools, automatic idle capture, manual session capture, and historical sync.
See [Access Mem Anywhere](/docs/remote-access).
## Troubleshooting [#troubleshooting]
**nmem not found.** Install with `pip install nmem-cli`, then run `nmem status` to verify.
**Server not responding.** Start the Nowledge Mem desktop app, or check `nmem status` for diagnostics.
**Plugin not loading.** Re-run `opencode plugin opencode-nowledge-mem -g --force`, confirm `"opencode-nowledge-mem"` appears in your `opencode.json` plugin array, then restart OpenCode.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code) · [Pi](/docs/integrations/pi) · [Hermes Agent](/docs/integrations/hermes) · [OpenClaw](/docs/integrations/openclaw) · [Alma](/docs/integrations/alma)
* Plugin source: [nowledge-mem-opencode-plugin](https://github.com/nowledge-co/community/tree/main/nowledge-mem-opencode-plugin)
# Other Chat AI (/docs/integrations/other-chat-ai)
Both DeepChat and LobeHub ship with Nowledge Mem built in. No server config, no MCP setup. Just toggle on.
## DeepChat [#deepchat]
### Enable MCP in DeepChat [#enable-mcp-in-deepchat-step]
Toggle on the switch under Settings>MCP Settings
### Enable Nowledge Mem [#enable-nowledge-mem-step]
Toggle on the nowledge-mem switch under Custom Servers
## LobeHub [#lobehub]
LobeHub (formerly LobeChat) offers one-click install from its plugin marketplace.
### One-click install [#one-click-install-step]
### Confirm in the install dialog [#confirm-in-the-install-dialog-step]
Click Install in the dialog
## Related [#related]
* [Connectors overview](/docs/integrations): native connectors, reusable packages, MCP, and browser capture
* [Claude Code](/docs/integrations/claude-code) · [Claude Desktop](/docs/integrations/claude-desktop) · [Codex](/docs/integrations/codex-cli) · [Alma](/docs/integrations/alma) · [OpenClaw](/docs/integrations/openclaw) · [Raycast](/docs/integrations/raycast)
# Paseo (/docs/integrations/paseo)
Paseo runs coding agents such as Claude Code, Codex, Copilot, OpenCode, Pi, and OMP on your own machine.
Nowledge Mem should connect to those launched AI tools. Paseo is the orchestration layer: it decides which worker runs, while the launched tool owns MCP, hooks, and transcript files.
Paseo's own MCP tools are for orchestration, such as creating agents or worktrees. Keep using them if you like. They do not replace the Nowledge Mem connector inside the launched AI tool, and they do not automatically capture every transcript for Mem.
## What You Need [#what-you-need]
1. Nowledge Mem is running on the machine where Paseo starts agents.
2. The AI tools Paseo launches are already connected to Mem, such as [Codex](/docs/integrations/codex-cli), [Claude Code](/docs/integrations/claude-code), [OpenCode](/docs/integrations/opencode), [Pi](/docs/integrations/pi), or [OMP](/docs/integrations/omp).
3. You know which Paseo agents are durable roles, not one-off tasks.
## First Useful Setup [#first-useful-setup]
Connect the launched AI tool first. For example, if Paseo starts Codex, install and verify the Codex connector. If it starts Pi, install and verify the Pi package. If it starts OMP, install and verify the OMP plugin.
If a Paseo agent represents a stable role, create one Mem AI Identity:
```bash
nmem agents upsert cindy \
--name "Cindy" \
--default-space onboarding \
--instructions "Help with onboarding. Explain one step at a time."
```
Then pass the identity into that launched child runtime:
```bash
NMEM_AGENT_ID=cindy
```
Leave `NMEM_AGENT_ID` unset for one-off advisors, short-lived implementation agents, and generic provider presets. Those can still use Mem through the child tool connector; they just do not need a named identity.
## Keep Source App Honest [#keep-source-app-honest]
Do not label every child session as `paseo`.
Use the launched AI tool as `source_app`:
* Paseo starts Codex: `source_app=codex`
* Paseo starts Claude Code: `source_app=claude-code`
* Paseo starts OpenCode: `source_app=opencode`
* Paseo starts Pi: `source_app=pi`
* Paseo starts OMP: `source_app=omp`
This keeps thread filters, icons, and capture paths correct. The Mem AI Identity is the worker's long-term role; the source app is the tool that actually produced the transcript.
## What Syncs [#what-syncs]
Supported child-tool sessions sync in two ways.
### While You Work [#while-you-work]
Automatic new-thread capture comes from the connector installed in the launched AI tool.
If Paseo starts Codex, install the Codex connector. If Paseo starts Claude Code, install the Claude Code connector. If Paseo starts OpenCode, Pi, or OMP, install those packages. Paseo can run those tools, but Paseo itself does not provide a Mem hook that fires after every child turn.
### Backfill Older Paseo Agents [#backfill-older-paseo-agents]
Older Paseo-managed sessions can be imported from Paseo's local agent registry:
```bash
nmem t sync --from paseo --all-projects --apply
```
That command reads Paseo's agent records, finds supported child sessions, and imports the real child transcript. Imported threads keep the child source, such as `codex`, `claude-code`, `opencode`, `pi`, or `omp`; they are not labeled as `paseo`.
The import is safe to rerun. Paseo-guided sync uses the same child thread id as direct child-tool sync, so a Codex session imported through Paseo still lands on the same `codex-*` thread instead of creating a second `paseo-*` copy.
Paseo's terminal activity, schedules, and chat rooms are separate. Nowledge Mem can import them directly only if Paseo later exposes message-level transcript export, API, or hook data for those surfaces.
## What Success Looks Like [#what-success-looks-like]
Inside the AI tool launched by Paseo, run:
```bash
nmem --json context --source-app codex
```
Use the matching source app for the launched tool. If the child runtime received `NMEM_AGENT_ID=cindy`, the Context Bundle should show Cindy's identity and default space.
From a normal terminal, pass the identity explicitly:
```bash
nmem --json context --agent-id cindy --source-app codex
```
## Next [#next]
* [Codex](/docs/integrations/codex-cli)
* [Claude Code](/docs/integrations/claude-code)
* [OpenCode](/docs/integrations/opencode)
* [Pi](/docs/integrations/pi)
* [OMP](/docs/integrations/omp)
* [Customize Connector Behavior](/docs/integrations/customize-behavior)
# Pi × Nowledge Mem (/docs/integrations/pi)
Give this line to your agent. It should use the universal install skill first; this page remains the behavior and troubleshooting reference:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Pi. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
```bash title="One-liner install"
pi install npm:nowledge-mem-pi
```
Pi is a minimal, extensible terminal coding agent. Nowledge Mem adds the layer above: knowledge from all your other AI tools, decisions made in Claude Code, preferences set in Cursor, insights from ChatGPT, searchable inside Pi. After you install the package, completed Pi conversations also sync back to Nowledge Mem as threads, so future tools can find what happened in Pi.
The package now has two automatic paths: Pi receives your Context Bundle or Working Memory at session startup, and completed Pi conversations are captured as searchable threads. Skills remain available for live search, saving decisions, and explicit handoffs.
## Before You Start [#before-you-start]
* **Nowledge Mem** running locally ([installation](/docs/installation))
* **Pi** installed
* **`nmem` CLI** in your PATH. In Nowledge Mem go to **Settings → Preferences → Developer Tools → Install CLI**, or `pip install nmem-cli`
```bash
nmem status # Nowledge Mem is running
pi --version # Pi is available
```
## Setup [#setup]
### Install the package [#install-the-package-step]
```bash
pi install npm:nowledge-mem-pi
```
### Verify the integration [#verify-the-integration-step]
Ask Pi to check your Nowledge Mem connection:
```
Is Nowledge Mem connected? Run the status skill.
```
You should see connection details and a confirmation that the server is reachable. That's success: Pi can now see knowledge from your other tools.
Start a fresh Pi session after install or update. Pi should already have a Nowledge Mem startup block in its system context; it should not need to run the `read-working-memory` skill just to know today's Context Bundle.
## Update [#update]
```bash
pi update
```
Restart Pi after updating so the Nowledge Mem extension reloads.
## Import Older Sessions [#import-older-sessions]
Automatic sync starts after the package is installed. If you have older Pi sessions you want in Nowledge Mem, run a one-time history import.
Preview first:
```bash
nmem t sync --from pi --limit 20
```
Then import:
```bash
nmem t sync --from pi --apply
```
The command reads Pi session files on this machine and writes them to the Mem server configured for your CLI or extension. It is safe to run again: Pi session IDs become stable thread IDs, and repeated messages are deduplicated.
Useful filters:
```bash
nmem t sync --from pi --session-dir ~/.pi/agent/sessions --limit 20
nmem t sync --from pi --space work --apply
```
When you pass `--session-dir`, only that directory is scanned. Without it, the command uses Pi's standard session locations.
If your installed `nmem` does not have `t sync` yet, use the package fallback:
```bash
npx -p nowledge-mem-pi nowledge-mem-pi-sync --apply
```
## Customize Safely [#customize-safely]
Use your project's own `AGENTS.md`, not the installed package cache.
* Merge the package guidance into `AGENTS.md` when you want Pi to search or save more proactively in this repo
* Keep package files as shipped defaults so updates stay clean
Pi does not expose a separate durable override file beyond its normal project guidance surface. For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## What You Can Do [#what-you-can-do]
**Keep Pi conversations searchable**
The package includes a native Pi extension. After installation, completed turns and session boundaries sync the active Pi session branch into a `pi` thread in Nowledge Mem. `/new`, resume, compaction, and clean exit all get a final bounded flush.
**Find knowledge from other tools**
Ask "what did we decide about the database?" and Pi can search across decisions you made in Claude Code, insights from ChatGPT, notes from Cursor, not just this session.
**Save knowledge for everywhere**
When you reach a conclusion in Pi, `distill-memory` lets Pi save it so your next Claude Code session, Cursor project, or ChatGPT conversation can find it too.
**Start with today's context**
The extension injects Context Bundle first, then falls back to Working Memory when needed. Pi starts with owner identity, AI Identity, active scope, Rules, and today's priorities when your Mem server supports them.
Project `AGENTS.md` is still useful, but for behavior rather than bootstrapping: use it to make Pi search and save more proactively in a specific repo.
**Create resumable handoffs**
Automatic thread sync keeps the transcript available. When you ask Pi to save a handoff, you also get a concise structured summary you can pick up in Claude Code or any other tool.
## Skills [#skills]
| Skill | What it does |
| --------------------- | ---------------------------------------------------------------------- |
| `read-working-memory` | Read today's Working Memory: focus areas, priorities, recent activity. |
| `search-memory` | Search knowledge from all your tools. Supports label and date filters. |
| `distill-memory` | Save a decision, insight, or preference so any tool can find it. |
| `save-thread` | Create an extra structured handoff summary when you ask for one. |
| `status` | Connection and configuration diagnostics. |
## Configuration [#configuration]
No config needed for local use.
| Env Variable | Default | What it does |
| -------------------- | ----------------- | --------------------------------------------------- |
| `NMEM_API_URL` | *(local)* | Remote Nowledge Mem server URL |
| `NMEM_API_KEY` | *(none)* | API key for remote access |
| `NMEM_SPACE` | *(default space)* | Optional lane for this Pi process |
| `NMEM_AGENT_ID` | *(none)* | Optional Mem AI Identity for orchestrated Pi agents |
| `NMEM_HOST_AGENT_ID` | *(none)* | Advanced external alias |
For a persistent shared setup, configure this machine once with `nmem config client ...`. The Pi extension uses the same `~/.nowledge-mem/config.json` as the CLI. Environment variables still take priority when you need a temporary override.
### Remote access [#remote-access]
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
See [Access Mem Anywhere](/docs/remote-access).
## Troubleshooting [#troubleshooting]
**nmem not found.** Install with `pip install nmem-cli`, then run `nmem status` to verify.
**Server not responding.** Start the Nowledge Mem desktop app, or check `nmem status` for diagnostics.
**Skills not loading.** Run `pi list` to confirm the package is installed. If `nowledge-mem-pi` does not appear, reinstall with `pi install npm:nowledge-mem-pi`.
**Pi conversations are not appearing in Threads.** Restart Pi after installing or updating, then run a short conversation with both a user message and an assistant reply. Check:
```bash
nmem t list --source pi -n 5
```
The extension intentionally skips one-message sessions so `/new` or empty starts do not create noise.
**Older Pi conversations are missing.** Automatic sync cannot see conversations that happened before the package was installed. Use `nmem t sync --from pi` to preview and import historical Pi session files.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code) · [OpenCode](/docs/integrations/opencode) · [Hermes Agent](/docs/integrations/hermes) · [OpenClaw](/docs/integrations/openclaw) · [Alma](/docs/integrations/alma) · [Bub](/docs/integrations/bub)
* Plugin source: [nowledge-mem-pi-package](https://github.com/nowledge-co/community/tree/main/nowledge-mem-pi-package)
# Proma × Nowledge Mem (/docs/integrations/proma)
Give this line to your agent if you want it to help with setup:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for Proma. Verify with nmem status, startup context, and a saved Proma thread, then summarize what changed.
```
Proma can use Nowledge Mem in three ways:
* **MCP tools** let Proma search memories, save durable knowledge, and browse Mem when the task needs it.
* **Lifecycle hooks** save Proma conversations into Mem threads.
* **Startup context** writes your current Mem context into Proma's workspace `CLAUDE.md`, so new Proma sessions begin with the right memory.
Proma v0.13.0 and newer include a Nowledge Mem card in Proma's Memory settings. Start there if you are setting this up for the first time: it copies a setup prompt you can paste into Proma Agent mode. Keep this page open for the exact files, update steps, and verification checks.
Open a new Proma session and ask What was I working on?. Then send a message with a unique phrase, wait for Proma to reply, and run nmem t search "that phrase" --source proma. You should see the Proma thread in Mem.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server.
* Proma is installed.
* Python 3.9+ is available as `python3`.
* `nmem` works in your terminal.
```bash
nmem status
```
If `nmem` is missing, install it from the Mem desktop app developer tools or run:
```bash
pip install nmem-cli
```
## Install [#install]
If you are on Proma v0.13.0 or newer, open **Proma Settings → Memory → Nowledge Mem**, copy the setup prompt, and paste it into Proma Agent mode. The manual steps below are the same contract, written out so you can audit or repair the setup.
The examples use Proma's `default` workspace. If your workspace has a different name, replace `default` with the directory name under `~/.proma/agent-workspaces/`.
If your platform exposes Python only as `python`, replace `python3` with `python` in the hook commands.
### Restart Proma \[step] [#4-restart-proma-step]
Restart Proma after changing MCP, hooks, or skills.
## What Happens [#what-happens]
* `UserPromptSubmit` saves the current Proma thread before the next user turn.
* `Stop` saves again after a response, so missed or delayed transcript writes are covered.
* The save hook reads Proma transcripts from `~/.proma/sdk-config/projects/**/.jsonl` and writes them as source `proma`.
* `SessionStart` refreshes the Nowledge Mem block inside `~/.proma/agent-workspaces/default/CLAUDE.md`.
* `Stop` asyncRewake can push a compact Working Memory reminder after assistant turns.
Proma's current Claude Agent SDK does not reliably inject SessionStart stdout as model context. That is why this connector writes a marked `CLAUDE.md` block instead:
```markdown
...
```
Keep your own Proma instructions outside that block, or in `CLAUDE.md.template`.
## Update [#update]
```bash
cd /tmp/nowledge-community
git pull
cp nowledge-mem-proma-plugin/hooks/save-to-nmem.py ~/.proma/scripts/
cp nowledge-mem-proma-plugin/hooks/read-working-memory.py ~/.proma/scripts/
chmod +x ~/.proma/scripts/save-to-nmem.py ~/.proma/scripts/read-working-memory.py
cp -R nowledge-mem-proma-plugin/skills/{read-working-memory,search-memory,distill-memory,save-thread,status} ~/.proma/agent-workspaces/default/skills/
```
Then merge the latest `nowledge-mem-proma-plugin/hooks/hooks.json` into `~/.proma/sdk-config/.claude/settings.json` and restart Proma.
## Remote Mode [#remote-mode]
For MCP, keep the remote URL and key in Proma's `mcp.json`.
For hooks and CLI fallback, configure the local `nmem` client once on the machine running Proma:
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
## Troubleshooting [#troubleshooting]
**MCP tools do not appear.** Confirm `mcp.json` uses `servers` as the top-level key, then restart Proma.
**Startup context does not appear.** Run `python ~/.proma/scripts/read-working-memory.py`, then check `~/.proma/agent-workspaces/default/CLAUDE.md` for the `nowledge-mem:start` block.
**Threads do not appear in Mem.** Wait for Proma to finish a turn, then check `~/.proma/logs/nm-hooks.log` and search with `nmem t search "" --source proma`.
**Remote MCP works, but hooks do not.** MCP uses Proma's `mcp.json`; hooks use the local `nmem` client config. Set both to the same remote Mem server.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Claude Code](/docs/integrations/claude-code)
* [Remote access](/docs/remote-access)
# Raft (/docs/integrations/raft)
Raft can run several named agents on the same computer. Nowledge Mem treats those agents as separate workers, not as one anonymous Codex or Claude session.
The setup is deliberately small: connect the AI tool Raft launches first, then set one environment variable on each Raft agent.
## What You Need [#what-you-need]
1. Nowledge Mem is running.
2. The AI tool Raft launches is already connected to Mem, such as [Codex](/docs/integrations/codex-cli) or [Claude Code](/docs/integrations/claude-code).
3. Each Raft worker has a stable role, such as Cindy, Alice, or Reviewer.
## First Useful Setup [#first-useful-setup]
Create one Mem AI Identity for the Raft worker:
```bash
nmem agents upsert cindy \
--name "Cindy" \
--default-space onboarding \
--instructions "Help with onboarding. Explain one step at a time."
```
This creates the Mem AI Identity named Cindy. Its command and environment ID is `cindy`.
This command only creates the identity record. It does not make every Codex session use Cindy. The identity is used only where you set `NMEM_AGENT_ID=cindy` or explicitly pass `agent_id="cindy"`.
Then open the Raft agent's runtime config and add one environment variable:
```bash
NMEM_AGENT_ID=cindy
```
That is enough when the Mem AI Identity already has a default space.
## Moving Cindy Later [#moving-cindy-later]
The Cindy identity belongs to Mem, not to Raft. If you later move Cindy to another orchestrator, keep `NMEM_AGENT_ID=cindy` and configure the new launcher to pass that environment variable.
The AI tool can change too. Cindy can start in Codex and later run in Pi or Claude Code. In that case, update the connector and `--source-app` to the new AI tool, but keep the same Mem AI Identity.
If you need a related but different worker, create a new identity such as `cindy-reviewer`. That keeps Cindy stable while letting the new worker evolve its own Rules.
## When To Add Space [#when-to-add-space]
`NMEM_SPACE` is optional. It applies to the whole Raft runtime process.
Use it only when this Raft agent should override the identity's default space for every Mem read and write during that run:
```bash
NMEM_SPACE=onboarding
```
If the agent may work across different projects, leave `NMEM_SPACE` unset and change the active space from Mem or from the command the agent runs.
## Do Not Add A Second Identity By Default [#do-not-add-a-second-identity-by-default]
Most users should not set `NMEM_HOST_AGENT_ID`.
Use `NMEM_HOST_AGENT_ID` only when an integration author or advanced user needs to map an immutable external worker ID, such as `raft:`, onto a Mem AI Identity. For normal Raft setup, `NMEM_AGENT_ID=cindy` is clearer and enough. The legacy `slock:` prefix remains supported.
## Keep Execution Traces Out of Threads [#keep-execution-traces-out-of-threads]
Raft's managed compute uses Codex as a worker, but Raft owns the human conversation through its inbox and message transport. The Codex rollout records control notices and tool execution; replies sent with Raft's messaging tool are not preserved there as normal Codex assistant messages. Importing that rollout would create a misleading Thread.
Nowledge Mem therefore skips Codex rollouts whose structured session originator is `raft-daemon`. The legacy `slock-daemon` originator remains supported. This is checked per transcript, so ordinary Codex sessions on the same computer continue to capture automatically.
Use Mem skills or MCP inside Raft for Working Memory, recall, and durable saves. Lossless Raft conversation history requires a Raft-native conversation connector; until that boundary is available, do not use `nmem t save --from codex` for a Raft-managed worker.
## What Success Looks Like [#what-success-looks-like]
With `nmem` 0.9.0 or later, start a fresh Raft worker session and ask it to check Mem:
```bash
nmem --json context --source-app codex
```
Inside the Raft worker, the command should inherit `NMEM_AGENT_ID=cindy` and return the worker identity you configured. If you run the same check from a normal terminal instead, pass the identity explicitly:
```bash
nmem --json context --agent-id cindy --source-app codex
```
Memory calls inside the worker use `codex`, `claude-code`, or whichever runtime Raft launched as their source. A future native Raft Thread connector will use `raft` for the human-visible conversation and retain the child runtime as metadata.
## Next [#next]
* [Codex](/docs/integrations/codex-cli)
* [Claude Code](/docs/integrations/claude-code)
* [Customize Connector Behavior](/docs/integrations/customize-behavior)
# Raycast (/docs/integrations/raycast)
Source: [community/nowledge-mem-raycast](https://github.com/nowledge-co/community/tree/main/nowledge-mem-raycast)
This page is the **Nowledge Mem Raycast extension**: keyboard-first commands against Mem over the API. **Raycast AI Chat** history does not ship as a vendor export; bring it into Threads with the community tool and Mem bulk import. See [Import existing conversations](/docs/import-existing-conversations), the [raycast-ai-exporter](https://github.com/daveonkels/raycast-ai-exporter) community tool, and [Bulk import formats](/docs/threads#bulk-import).
## Install [#install]
**Raycast Store:** search "Nowledge Mem" or [open the store link](https://www.raycast.com/wey-gu/nowledge-mem) to add the extension directly.
**From source** (for development or customization):
```bash
git clone https://github.com/nowledge-co/community.git
cd community/nowledge-mem-raycast
npm install && npm run dev
```
You can connect in two ways:
* **Local default:** keep the default `http://127.0.0.1:14242`
* **Remote Mem:** set **Server URL** and **API Key** in Raycast preferences, or if you want one shared config for Raycast + CLI + other plugins, run:
```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
```
Raycast also supports one optional fixed lane through a **Space** preference. Use it when this Raycast profile always belongs to one named lane such as `Research Agent`. Leave it empty to stay on **Default**.
Most commands work with either local or remote Mem. `Edit Working Memory` is the one local-only convenience command because it edits the **Default** Working Memory file on your own machine.
## Commands [#commands]
| Command | What it does |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| **Search Memories** | Semantic search with relevance scores. When the search box is empty, it shows recent memories |
| **Add Memory** | Save a memory with title, content, and importance |
| **Read Working Memory** | Read your daily briefing through the Mem API |
| **Edit Working Memory** | Edit the Default Working Memory file from Raycast on your local machine |
## Customize Safely [#customize-safely]
Raycast is a launcher-style integration, not an agent runtime with its own project instruction file.
* Use Raycast preferences for durable changes such as server URL, API key, and fixed space
* Do not edit extension source unless you are developing the extension itself
For the full host-by-host map, see [Customize Integration Behavior](/docs/integrations/customize-behavior).
## Spaces [#spaces]
Raycast is a launcher. The best space model here is one optional fixed lane:
* Leave **Space** empty to use the shared `nmem` client space, which is normally **Default**
* Set **Space** when this Raycast profile always belongs to one stable lane
* Do not expect Raycast to derive per-agent routing on its own
When you do set a space, **Search Memories**, **Add Memory**, and **Read Working Memory** all follow it automatically. `Edit Working Memory` stays intentionally local and Default-only.
## Best Flow [#best-flow]
* Use **Search Memories** when you want the fastest answer
* Use **Add Memory** when you want to save something quickly from the keyboard
* Use **Read Working Memory** when you want today’s focus without opening the full app
Graph exploration is not part of the Raycast extension. For graph work, use the Mem app or an MCP-capable connector such as Claude Code or Codex.
## Related [#related]
* [Connectors overview](/docs/integrations): native connectors, reusable packages, MCP, and browser capture
* [Claude Code](/docs/integrations/claude-code) · [Claude Desktop](/docs/integrations/claude-desktop) · [Codex](/docs/integrations/codex-cli) · [Alma](/docs/integrations/alma) · [OpenClaw](/docs/integrations/openclaw) · [Other Chat AI](/docs/integrations/other-chat-ai)
# WorkBuddy × Nowledge Mem (/docs/integrations/workbuddy)
Paste this into WorkBuddy:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for WorkBuddy. Verify with nmem status and the Context Bundle or Working Memory check, then run a short session and confirm the thread appears with nmem t list --source workbuddy.
```
WorkBuddy can use Nowledge Mem through the CodeBuddy-compatible plugin system. The plugin gives WorkBuddy startup context, Mem MCP tools, quick commands, and lifecycle hooks that sync WorkBuddy's local transcript into Mem Threads.
CodeBuddy's release notes document that WorkBuddy uses an independent `.workbuddy/` configuration directory, separated from CodeBuddy's `.codebuddy/`. The Nowledge Mem connector treats WorkBuddy as its own source: `nmem t sync --from workbuddy`.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* WorkBuddy is installed
* `nmem` works on the same machine as WorkBuddy
```bash
nmem status
```
If `nmem` exists but rejects `t sync --from workbuddy` or `config mcp show --host workbuddy`, update the CLI before debugging MCP or session sync:
* Desktop-bundled CLI: open Mem and run **Settings → Preferences → Developer Tools → Install bundled CLI** again.
* PyPI CLI: `python3 -m pip install --user --upgrade nmem-cli`
* pipx CLI: `pipx upgrade nmem-cli`
If WorkBuddy runs on a different machine from the Mem desktop app, install the standalone CLI there first and point it at your Mem server:
```bash
python3 -m pip install --user nmem-cli
nmem config client set url https://your-server
nmem config client set api-key your-key
```
## Install The Plugin [#install-the-plugin]
Add the Nowledge community marketplace, then install the plugin:
```text
/plugin marketplace add nowledge-co/community
/plugin install nowledge-mem@nowledge-community
```
The marketplace is backed by `community/.workbuddy-plugin/marketplace.json`. The shared plugin includes:
* a WorkBuddy plugin manifest
* a local MCP server for `http://127.0.0.1:14242/mcp/`
* startup guidance and a Nowledge Mem skill
* hooks for `Stop`, `SessionEnd`, `PreCompact`, and `SubagentStop`
* quick commands under `/nowledge-mem:*`
For remote Mem or authenticated localhost, generate a WorkBuddy MCP block:
```bash
nmem config mcp show --host workbuddy
```
Paste the generated `nowledge-mem` server into `~/.workbuddy/.mcp.json`, `$WORKBUDDY_CONFIG_DIR/.mcp.json`, or a project `.mcp.json`.
## Thread Sync [#thread-sync]
WorkBuddy passes `session_id` and `transcript_path` to lifecycle hooks. The Nowledge Mem plugin uses those fields instead of guessing where the latest transcript is.
After install, the hook runs:
```bash
nmem --json t sync --from workbuddy --session-id --session-dir --all-projects --apply
```
That command runs on the WorkBuddy machine, reads the local transcript under `$WORKBUDDY_CONFIG_DIR/projects` or `~/.workbuddy/projects`, and uploads normalized messages to your local or remote Mem server. It is safe to rerun; Mem deduplicates repeated imports.
## Verify [#verify]
Start a new WorkBuddy session and ask:
```text
Is Nowledge Mem connected? Read my current context.
```
Success means WorkBuddy can call the Nowledge Mem MCP tools and return Context Bundle, Working Memory, or an empty-but-successful memory result.
Then finish a short exchange and check:
```bash
nmem t list --source workbuddy -n 5
```
You should see the recent WorkBuddy thread after the hook has run. If hooks do not appear to run, check:
```bash
tail -n 50 ~/.workbuddy/logs/nowledge-mem-hook.log
```
If you set `WORKBUDDY_CONFIG_DIR`, check that directory's `logs/nowledge-mem-hook.log` instead.
## Import Older Sessions [#import-older-sessions]
Preview first:
```bash
nmem t sync --from workbuddy --limit 20
```
Import when the preview looks right:
```bash
nmem t sync --from workbuddy --apply
```
For a custom WorkBuddy config directory:
```bash
WORKBUDDY_CONFIG_DIR="$HOME/.my-workbuddy-config" nmem t sync --from workbuddy --apply
```
## Customize Behavior [#customize-behavior]
Use WorkBuddy's own instruction surfaces when available:
* `~/.workbuddy/CODEBUDDY.md` or `~/.workbuddy/MEMORY.md` for personal global guidance
* project `CODEBUDDY.md` for shared workspace guidance
* `.workbuddy/rules/*.md` for structured project rules
Do not edit installed plugin files. Marketplace updates can replace them.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [CodeBuddy guide](/docs/integrations/codebuddy)
* [Threads](/docs/threads)
* WorkBuddy: [Product page](https://www.codebuddy.cn/work/)
* CodeBuddy docs: [Plugin Reference](https://www.codebuddy.ai/docs/cli/plugins-reference) · [Hooks Reference](https://www.codebuddy.ai/docs/cli/hooks) · [MCP](https://www.codebuddy.ai/docs/cli/mcp)
# ZCode × Nowledge Mem (/docs/integrations/zcode)
Paste this into ZCode:
```text
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for ZCode. Verify with nmem status and the Context Bundle or Working Memory check, then summarize what changed.
```
ZCode supports MCP servers and `SKILL.md`-based skills. Use those native settings to give ZCode access to your Nowledge Mem knowledge without editing ZCode internals.
## Before You Start [#before-you-start]
* Nowledge Mem is running locally, or you have a reachable remote Mem server
* ZCode is installed
* `nmem` works on the same machine as ZCode
```bash
nmem status
```
## Setup [#setup]
Generate the MCP config:
```bash
nmem config mcp show --host zcode
```
In ZCode:
1. Open **Settings → MCP Servers**.
2. Add the generated `nowledge-mem` server. ZCode supports configured MCP servers through the settings UI.
3. Open **Settings → Skills**.
4. Import or copy the Nowledge Mem skills.
5. Restart or reload ZCode Agent.
## Verify [#verify]
Ask ZCode:
```text
Search my memories for recent decisions about this project.
```
Success means the ZCode Agent can call the Nowledge Mem MCP tools and returns results or a clean empty result.
## Session Capture [#session-capture]
ZCode has a plugin model that can bundle skills, MCP servers, hooks, and commands. Nowledge Mem does not yet publish a ZCode-native hook package, so this connector does not promise automatic transcript capture. Use handoff summaries when a ZCode conversation should be searchable later.
## Related [#related]
* [Connectors overview](/docs/integrations)
* [Kimi Code](/docs/integrations/kimi-code) · [MiMo Code](/docs/integrations/mimo-code) · [OMP](/docs/integrations/omp)
* ZCode docs: [Plugin](https://zcode.z.ai/en/docs/plugin), [MCP Servers](https://zcode.z.ai/en/docs/mcp-services), [Skills](https://zcode.z.ai/en/docs/skill)
# Self-hosted auto-update (/docs/self-host/auto-update)
Self-hosted Docker servers can check for new Nowledge Mem releases from the web app. Installing those releases from the browser is opt-in, because it changes the server itself.
In-app auto-update requires the official `community/docker` layout and its `nmemctl` helper. If you installed Mem through a NAS app store, a NAS Container Manager template, Portainer, Unraid, or your own custom compose file, the app may still show that a new version exists, but it cannot safely rewrite that deployment for you. Update from the same place you installed it, or use your own Docker image pull/recreate flow.
If your Settings page says auto-update is not configured, SSH to the server once and run:
```bash
cd community/docker
./nmemctl auto-update enable
```
That command creates a per-deploy updater token, starts a small companion updater container, and lets the web app download and install future Mem images. If `community/docker` or `./nmemctl` is not present on your server, you are not on this update path.
The updater companion container needs access to Docker so it can replace the Mem container. That is why browser installs are disabled until you explicitly enable them on the server host.
## What changes in the app [#what-changes-in-the-app]
After official auto-update is enabled:
* The title bar shows an update badge when a newer server image is available.
* Settings shows the current server version, the latest available version, and a link to the release notes.
* Download pulls the image in the background without taking Mem offline.
* Install takes a pre-upgrade snapshot, recreates the container, and reconnects the page when the server is back.
Every install keeps the last three pre-upgrade snapshots in `./cache`. If the new image fails to boot, Settings shows the snapshot path so you can restore it from the server:
```bash
./nmemctl import --force
```
## Useful commands [#useful-commands]
```bash
./nmemctl auto-update status
./nmemctl auto-update rotate
./nmemctl auto-update upgrade
./nmemctl auto-update disable
```
* `status` shows whether auto-update is enabled and which snapshots are retained.
* `rotate` replaces the updater token.
* `upgrade` updates the companion updater container itself.
* `disable` removes the updater container but keeps existing snapshots.
## Remote installs [#remote-installs]
Checking for updates is always safe and available from the web UI. Download and Install are server-side operations, so they are protected by the server's remote-operations setting.
`./nmemctl auto-update enable` configures this for the normal web-upgrade flow. If you turned it off later, enable **Remote server upgrades** from Settings when you are on a trusted private network, or run upgrades from SSH:
```bash
./nmemctl upgrade
```
## More detail [#more-detail]
For the full Docker deployment guide, including backup, memory sizing, TLS, and migration, see [Docker Deployment](/docs/docker).
# Search Through Time (/docs/use-cases/bi-temporal)
## The Problem [#the-problem]
The board asks: *"Why did you choose React Native over Flutter in Q1?"*
You remember the decision. But you remember it through the lens of everything that happened after: the pivot, the performance issues, the rewrite.
You need to answer: **What did you know THEN?**
> "I can search my notes for 'React Native'. But I can't search for 'what I believed in March about React Native'."
## The Solution [#the-solution]
Nowledge Mem uses **bi-temporal search**: two dimensions of time that let you find exactly what you're looking for.
**Event Time**: When did the thing actually happen?
**Record Time**: When did you capture it?
Search either. Search both. Travel through your own history.
Blog: [How We Taught Nowledge Mem to Forget](https://nowledge-labs.ai/blog/memory-decay-temporal).
Documentation about [Search & Relevance](/docs/search-relevance).
## How It Works [#how-it-works]
### Natural Language Queries [#natural-language-queries]
Just search naturally. Nowledge Mem understands temporal intent:
> "What did I decide about React Native in Q1 2024?"
The system:
1. Detects temporal intent: "Q1 2024"
2. Searches memories where the **event** occurred in that period
3. Returns results with original context
No special syntax needed.
### Explicit Temporal Filters [#explicit-temporal-filters]
For precise control, use the advanced search:
| Filter | Meaning | Example |
| -------------------- | --------------------- | ---------- |
| **Event Date From** | Event happened after | 2024-01-01 |
| **Event Date To** | Event happened before | 2024-03-31 |
| **Record Date From** | Written down after | 2024-01-01 |
| **Record Date To** | Written down before | 2024-12-31 |
**Power Query Example:**
> Event Time: March 2024
> Record Time: Any
Returns: *"All memories about events from March 2024, regardless of when you recorded them."*
### Flexible Date Precision [#flexible-date-precision]
Nowledge Mem handles flexible dates:
* **Year**: "2024" -> Matches anything in 2024
* **Month**: "2024-03" -> Matches March 2024
* **Day**: "2024-03-15" -> Matches that specific day
The system preserves your original precision and displays accordingly.
## Knowledge Evolution [#knowledge-evolution]
Bi-temporal search gets even more powerful with Knowledge Evolution. Background Intelligence automatically detects when your thinking on a topic changes:
**Tuesday**: You save "Using PostgreSQL for the new service."
**Thursday**: You mention CockroachDB as a migration target.
**Friday**: Background Intelligence links them with an EVOLVES relationship and flags the tension.
Now when you search "database decisions," you don't just get isolated memories. You get the **evolution chain**: the original decision, the update, and the relationship between them. You can see exactly how your thinking shifted and when.
Evolution types:
* **Replaces**: Newer information makes older obsolete
* **Enriches**: Newer adds detail to older
* **Confirms**: Same conclusion from a different source
* **Challenges**: Contradictory information flagged for review
## Real Examples [#real-examples]
### Board Retrospective [#board-retrospective]
> **Query**: "architecture decisions in Q1 2024"
>
> **Result**: Original decision memos with Q1 context, plus evolution chains showing how decisions changed after
### Compliance Audit [#compliance-audit]
> **Query**: "security policies before the incident"
>
> **Result**: What policies existed before the breach, with record timestamps proving when they were documented
### Project Post-Mortem [#project-post-mortem]
> **Query**: "project-x assumptions from kickoff"
>
> **Result**: Original assumptions that turned out wrong, linked to the later insights that proved them wrong
## Knowledge Graph + Time [#knowledge-graph--time]
Your graph view has a **timeline slider** that filters nodes and edges by date range.
Set the range to "March 2024" and see:
* Only entities that existed then
* Only connections that were known then
* The state of your knowledge at that moment
Drag the slider forward and watch your understanding evolve. Play the animation to see knowledge accumulate over time.
## How Memory Decay Works [#how-memory-decay-works]
Not all memories age equally. Like your brain, Nowledge Mem:
* **Prioritizes recent memories** by default (30-day half-life)
* **Boosts frequently accessed** memories (logarithmic scaling)
* **Respects importance** scores you set (importance floor prevents full decay)
* **Learns from your behavior** (clicks, dwell time)
This means casual searches surface fresh, relevant results, but temporal searches bypass decay to find exactly what you asked for.
Temporal intent detection requires **Deep Mode** search. In Fast Mode, temporal references are matched by keywords only. Enable Deep Mode for queries like "recently working on" or "decisions from last quarter."
See [Search & Relevance](/docs/search-relevance) for the full technical breakdown of how scoring, decay, and temporal matching work.
## The Two Times [#the-two-times]
Understanding the difference is key:
| Question | Which Time? |
| ------------------------------------ | ----------- |
| "What did I decide in March?" | Event Time |
| "What did I write last week?" | Record Time |
| "Show recent notes about old events" | Both |
| "What did I know before the pivot?" | Event Time |
Most searches use **event time** because you're asking about when things happened.
**Record time** is useful for:
* Finding recent captures
* Reviewing what you've been documenting
* Auditing when knowledge was recorded
## Why This Matters [#why-this-matters]
Traditional search finds content. Temporal search finds **context**. Knowledge Evolution finds **the story**.
> "We didn't make a bad decision. We made the best decision with what we knew. Here's the proof. And here's exactly when and why our thinking changed."
Your memories are time-stamped, version-controlled, and historically accurate.
## Next Steps [#next-steps]
* [Own Your Knowledge](/docs/use-cases/shared-memory) -> Use any tool without losing context
* [See Your Expertise](/docs/use-cases/expertise-graph) -> Visualize your knowledge
* [Background Intelligence](/docs/advanced-features) -> Knowledge graph capabilities
# See Your Expertise (/docs/use-cases/expertise-graph)
## The Problem [#the-problem]
You've been learning for years. Building expertise. Accumulating knowledge.
But can you see it?
> I know I'm good at... stuff. Technical stuff. But if someone asked me to describe my expertise, I'd struggle. It's all intuition. Nothing concrete.
Your knowledge is invisible. Scattered across memories, notes, conversations. You can't see the patterns. The connections. The clusters of expertise.
## The Solution [#the-solution]
Nowledge Mem visualizes your knowledge as a **living graph**. Nodes are your memories and entities. Edges are relationships. And the graph **builds itself**: Background Intelligence automatically extracts entities and relationships from your memories overnight.
Run **community detection** and watch your expertise clusters emerge:
## How It Works [#how-it-works]
### The Graph Builds Itself [#the-graph-builds-itself-step]
You don't need to manually tag or categorize anything. Background Intelligence reads your memories and extracts:
* **Entities**: Technologies, people, concepts, projects
* **Relationships**: How they connect to each other
* **Evolution chains**: How your thinking on a topic has changed
This happens automatically. Save memories through any channel (auto-sync, browser extension, Timeline, `/sum`) and the graph grows on its own.
Automatic entity extraction requires a configured Remote LLM and the appropriate license for your build.
### Run Community Detection [#run-community-detection-step]
In the right panel, find **Graph Algo** and click Compute under **Clustering**.
The Louvain algorithm analyzes your knowledge structure and finds natural clusters:
| Community | Size | Theme |
| ------------------- | ----------- | ----------------------------- |
| Distributed Systems | 87 memories | Backend architecture, scaling |
| Team Leadership | 45 memories | Mentoring, communication |
| Performance | 62 memories | Optimization, profiling |
| Side Projects | 23 memories | Creative experiments |
Each cluster gets a colored "bubble" around its nodes.
### Travel Through Time [#travel-through-time-step]
The **timeline slider** at the bottom of the graph lets you filter by date range.
Drag to "January 2024" and see your knowledge at that point. Drag forward and watch new clusters form, existing ones grow, and connections multiply.
Play the animation to watch your expertise evolve over months. See when a new interest emerged, when it connected to existing knowledge, and when it grew into a full cluster.
### Explore and Discover [#explore-and-discover-step]
Navigate the graph:
* **Click** any node to see its details
* **Double-click** to expand neighbors
* **Shift+drag** to lasso-select multiple nodes
* **Press C** to toggle community bubbles
* **Press E** to expand selected node's neighbors
Find patterns you never noticed:
> Every leadership memory links back to debugging sessions. I lead by teaching debugging.
## What You'll Discover [#what-youll-discover]
### Expertise Clusters [#expertise-clusters]
Community detection reveals where your knowledge naturally groups:
* **Core strengths**: Large, dense clusters
* **Emerging areas**: Small but growing clusters
* **Bridges**: Nodes that connect multiple clusters (often your most unique skills)
### Knowledge Evolution [#knowledge-evolution]
Background Intelligence tracks how your thinking changes:
* **Tuesday**: "Using PostgreSQL for the new service"
* **Thursday**: "Considering CockroachDB for migration"
* **Friday briefing**: "Your database thinking is evolving"
These evolution chains appear as linked nodes in the graph. You can see exactly where your opinions shifted and follow the trail.
### Hidden Patterns [#hidden-patterns]
Explore and find:
* Recurring themes you never consciously tracked
* Connections between seemingly unrelated projects
* Your unique perspective and approach
* Gaps between related topics
## Asking AI About Your Graph [#asking-ai-about-your-graph]
With your graph in view, ask AI Now to interpret it:
> Based on my knowledge graph, what career paths fit me best?
AI Now synthesizes:
> Your memories show a unique intersection of deep systems knowledge with teaching ability. Your most central concepts (event-driven architecture, debugging) connect to both technical and leadership clusters. Consider: Staff Engineer, Developer Advocate, or Engineering Manager with technical focus.
Other questions to try:
* "What are my strongest expertise areas?"
* "Where are the gaps in my knowledge?"
* "What topics should I explore next?"
* "How has my focus shifted over time?"
## The Compound Effect [#the-compound-effect]
More memories = richer graph = deeper insights.
**After 1 month:**
> I can see my main topics, but clusters are small
**After 6 months:**
> Clear expertise areas. Unexpected connections emerging. Background Intelligence is finding patterns I missed.
**After 1 year:**
> I can literally see how my thinking has evolved. The connections I made last year laid groundwork for this year.
**For performance reviews:**
> I explored my graph before the review. Had concrete examples of growth across every dimension.
## Next Steps [#next-steps]
* [Background Intelligence](/docs/advanced-features) -> How the graph grows automatically
* [Own Your Knowledge](/docs/use-cases/shared-memory) -> Use any tool without losing context
* [Search Through Time](/docs/use-cases/bi-temporal) -> Temporal queries and evolution chains
# Overview (/docs/use-cases)
Nowledge Mem learns from your work with AI. It captures conversations through the right path for each supported tool, keeps sessions and memories searchable, and builds a knowledge graph that grows overnight. Connected tools can start with richer context.
Pick the use case that matches the problem you want to solve first. You do not need every part of Mem on day one.
Tell Claude once. Cursor can pick it up too. One knowledge base across the AI tools you connect to Mem.
Native save paths, connector live capture, local backfill, and browser capture keep important conversations searchable.
The board asks why you chose React Native. Find what you believed then, not what you know now.
Obsidian, Notion, PDFs, Word docs. One search covers all your knowledge sources.
The graph builds itself from your memories. Community detection reveals expertise clusters you didn't know you had.
A personal AI agent that can use your saved knowledge, files, and enabled plugins. Deep research, file analysis, and presentations on your machine.
## Three Things That Change [#three-things-that-change]
**It captures through the right path.** The browser extension grabs insights and thread backups from supported web AI chats. Native connectors capture new coding-agent work where the host supports hooks, local import backfills older sessions, and the Timeline is always there for direct capture.
**It learns while you sleep.** Background Intelligence detects when your thinking evolves, synthesizes reference articles from scattered memories, and flags contradictions. Your morning Working Memory briefing tells your AI tools what you're working on before you say anything.
**It goes where you go.** Native integrations, reusable workflow packages, and direct MCP all connect back to the same memory system. Switch tools freely. Your knowledge stays.
## How It Works [#how-it-works]
1. **Capture** -- browser capture, native save paths, connector live capture, local backfill, or direct Timeline input
2. **Connect** -- the system links it to everything you already know
3. **Grow** -- Background Intelligence builds evolution chains, crystals, and flags overnight
4. **Use** -- connected tools can find it when it's relevant
Your knowledge compounds in Mem, independent of any single tool.
## Ready to Start? [#ready-to-start]
Pick a use case above if one problem stands out. If not, go back to [Start Here](/docs/start-here) or [Getting Started](/docs/getting-started) and prove one small workflow first.
# Your Notes, Everywhere (/docs/use-cases/notes-everywhere)
## The Problem [#the-problem]
You've been taking notes for years. Obsidian. Notion. Maybe both.
Thousands of entries. Carefully tagged. Extensively linked.
And yet...
> I know I wrote about this. I just can't find it. The search is useless. The tags don't help.
Worse: Your AI assistant has no idea any of this exists. You're explaining context that's already in your notes. Every. Single. Time.
## The Solution [#the-solution]
We don't replace your note app. We **wire it into your knowledge**.
Keep using Obsidian, Notion, Apple Notes or folders of Markdown files exactly as you do now. Nowledge Mem connects to them, making your notes searchable alongside your memories in AI Now and across the AI tools you connect to Mem.
And with the **Library**, you can drop PDFs, Word documents, and presentations in too. Everything becomes searchable from one place.
## How It Works [#how-it-works]
### Connect Your Notes [#connect-your-notes-step]
**Obsidian:**
1. Open AI Now in Nowledge Mem
2. Go to **Plugins** -> Enable **Obsidian**
3. Set your vault path (e.g., `/Users/you/Documents/ObsidianVault`)
4. Done. AI Now can now search your vault
**Notion:**
1. Open AI Now -> **Plugins** -> Enable **Notion**
2. Click **Connect with Notion**
3. Authorize access in the browser popup
4. Your workspace is now accessible
### Import Documents to the Library [#import-documents-to-the-library-step]
Drop files directly into the Timeline input or open the Library view:
| Format | Extensions | What Happens |
| ----------------- | ----------- | -------------------------------------------- |
| **PDF** | .pdf | Text extracted, split into segments, indexed |
| **Word** | .docx, .doc | Parsed to text, segmented, indexed |
| **Presentations** | .pptx | Slide content extracted and indexed |
| **Markdown** | .md | Parsed and indexed directly |
Once indexed, document content is searchable alongside your memories and notes.
### Search Across Everything [#search-across-everything-step]
Ask AI Now any question:
> What do my notes say about quantum computing?
AI Now:
1. Searches your Obsidian vault
2. Searches your Notion workspace
3. Searches your Nowledge memories
4. Searches your Library documents
5. Combines and synthesizes results
One question. All your knowledge sources.
### Distill Into Memories [#distill-into-memories-step]
Found valuable notes? Turn them into permanent memories:
> Distill the key insights from these quantum computing notes
AI Now creates:
* **Insight**: "Quantum error correction requires O(n^2) qubits"
* **Decision**: "Focus on NISQ algorithms for near-term research"
* **Fact**: "IBM claimed quantum advantage Dec 2023"
These memories are now:
* Searchable with semantic understanding
* Connected in the knowledge graph
* Accessible across the AI tools you connect to Mem
* Part of your Working Memory briefing when relevant
#### Open Nowledge Mem [#open-nowledge-mem-step]
Open the Nowledge Mem app.
#### Click the AI Now tab [#click-the-ai-now-tab-step]
Select the **AI Now** tab in the sidebar.
#### Go to Plugins [#go-to-plugins-step]
Open **Plugins** in the sidebar.
#### Enable Obsidian [#enable-obsidian-step]
Find **Obsidian** and toggle it on.
#### Enter your vault path [#enter-your-vault-path-step]
Example: `/Users/yourname/Documents/ObsidianVault`
### What You Can Do [#what-you-can-do]
Once connected:
* Search notes by content: *"Find my notes about machine learning"*
* Read specific notes: *"Show me the note about project kickoff"*
* Reference in context: *"Based on my Obsidian notes about X, help me..."*
Your vault is read locally. Notes are never uploaded anywhere. Nowledge Mem just reads the files on your machine.
## Notion Integration [#notion-integration]
### Setup [#setup-1]
#### Open AI Now Plugins [#open-ai-now-plugins-step]
Open AI Now → **Plugins**.
#### Connect Notion [#connect-notion-step]
Find **Notion** and click **Connect**.
#### Authorize in the browser [#authorize-in-the-browser-step]
Complete authorization in the browser popup.
#### Select workspaces [#select-workspaces-step]
Select the workspaces you want to connect.
### What You Can Do [#what-you-can-do-1]
* Search your workspace: *"Find pages about quarterly planning"*
* Read page content: *"What's in my Product Roadmap page?"*
* Cross-reference: *"Compare my Notion notes with my memories about X"*
* Deep Research with both public information and private knowledge: *"What's the latest on quantum computing?"*
Notion uses secure OAuth. You control exactly which pages Nowledge Mem can access. Revoke anytime from Notion settings.
## Built-in Connectors [#built-in-connectors]
Some tools have Nowledge Mem built in:
* **DeepChat**: Toggle Nowledge Mem in settings. Your memories become available in every chat.
* **LobeHub**: Install from the marketplace. Full MCP integration.
* **Apple Notes (macOS)**: Search your Apple Notes through AI Now after enabling the built-in plugin.
Join the [Community](/docs/community) to request connectors.
## Next Steps [#next-steps]
* [AI Now](/docs/ai-now) -> Learn what else AI Now can do
* [Library](/docs/library) -> Import and search documents
* [See Your Expertise](/docs/use-cases/expertise-graph) -> Visualize your knowledge graph
* [Connectors](/docs/integrations) -> Full setup guides
# Never Lose a Session (/docs/use-cases/session-backup)
## The Problem [#the-problem]
You just had an epic debugging session. Three hours with Claude Code. You found a race condition, traced it through 15 files, built a bulletproof fix with tests.
But AI conversations are ephemeral. Context gets compacted, token limits hit, and sessions expire. That 200-message thread? The early context is already gone.
> "I solved this exact problem before. I just can't remember how. Or where. Or when."
## The Solution [#the-solution]
Your sessions can flow into Mem through the right path for each tool. Native integrations save real session transcripts where the host supports it. Local import backfills older coding-agent sessions from disk. Browser conversations from ChatGPT, Claude, and Gemini are captured by the extension. You only need exports when that is the source you already have.
When you're ready, distill a thread into permanent, searchable, graph-connected memories.
Pick one conversation you already care about, get it into Threads, then distill one useful memory from it. Once you can find both the original thread and the distilled takeaway later, this workflow is working.
## How It Works [#how-it-works]
### Sessions Reach Mem Through Different Paths [#sessions-reach-mem-through-different-paths-step]
**Native live capture (Claude Code, Codex, Gemini CLI, OpenCode):**
Dedicated connectors save the real transcript from the machine where the agent runs. For OpenCode, the plugin captures after OpenCode reports idle and flushes before compaction.
**Local backfill (Claude Code, Cursor, Codex, OpenCode):**
Nowledge Mem can scan local coding sessions from disk when you want older history in Threads. Use the import view or run `nmem t sync --from ` on the machine that stores those sessions.
**Native handoff-first paths (Droid, Cursor):**
Some tools already have a dedicated native package, but intentionally stop at resumable handoff summaries until a real transcript importer exists. That still gives you cross-session continuity without pretending to store the full recorded conversation.
**Browser capture (ChatGPT, Gemini, Claude Web):**
The Exchange v2 extension captures conversations from supported web AI chat platforms. Insights and thread backups flow into Mem as you chat.
**Manual distill or handoff:**
```
/sum -> Distill durable insights into memories
/save -> Create a resumable handoff or tool-specific save path, depending on the integration
```
### Distill Into Permanent Knowledge [#distill-into-permanent-knowledge-step]
Open a saved thread and click **Distill**. The AI reads the entire conversation and extracts:
* **Decisions**: "Chose sliding window over token bucket because..."
* **Insights**: "Race conditions in async callbacks need mutex locks"
* **Patterns**: "Testing time-based bugs requires mock clocks"
* **Facts**: "Redis SETNX provides atomic lock acquisition"
Each becomes a standalone, searchable memory with proper labels.
### Background Intelligence Connects It [#background-intelligence-connects-it-step]
Your new memories don't sit in isolation. Background Intelligence:
* Links them to previous work on the same codebase
* Detects if they update or contradict earlier decisions
* Connects them to related entities in the knowledge graph
* Surfaces them in your next morning's Working Memory briefing
Three months later, a colleague hits the same bug. Your briefing mentions it before they even ask.
### Search Anytime [#search-anytime-step]
Three months later, similar bug appears:
> Search: "payment race condition"
Nowledge Mem returns the full context: the problem, the debugging steps, the solution, the test approach.
No more re-solving solved problems.
## What Gets Captured [#what-gets-captured]
| Source | How | What You Get |
| ------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| **Claude Code** | Native connector save or local auto-sync | Full session with code context |
| **Gemini CLI** | Native extension `save-thread` | Real recorded Gemini session |
| **Droid** | Native connector `save-handoff` | Resumable handoff summaries inside Droid, with honest boundaries around full session import |
| **Codex** | Native connector Stop hook or local auto-sync | Full session with code context |
| **Cursor** | Plugin `save-handoff`, local auto-sync, or manual import | Resumable handoff summaries in the plugin, plus local conversation import on your machine |
| **OpenCode** | Native plugin idle-event capture; CLI/import backfill for older sessions | New conversations as they happen, plus searchable history when imported |
| **ChatGPT** | Browser extension (auto-capture) | Insights and full thread backups from web chats |
| **Claude Web** | Browser extension (auto-capture) | Insights and full thread backups from web chats |
| **Gemini** | Browser extension (auto-capture) | Insights and full thread backups from web chats |
| **More supported web AI chats** | Browser extension | The same capture model on supported sites |
## What Gets Extracted [#what-gets-extracted]
When you distill a thread, the AI creates memories categorized by type:
| Type | Example | Labels |
| -------------- | --------------------------------------- | ---------------------- |
| **Decision** | "Used Redis for distributed locking" | decision, architecture |
| **Insight** | "Async callbacks need careful ordering" | insight, debugging |
| **Procedure** | "Steps to reproduce race conditions" | procedure, testing |
| **Fact** | "SETNX returns 1 if key was set" | fact, redis |
| **Experience** | "Debugging session on payment service" | experience, project |
## The Compound Effect [#the-compound-effect]
One thread saved is useful. Ten threads saved is a knowledge base. A hundred threads? That's institutional memory.
> "Junior dev hit the same bug today. Sent them my memory. They fixed it in 20 minutes instead of 3 hours."
Your debugging sessions aren't just conversations. They're training data for your future self.
## Pro Tips [#pro-tips]
You don't need to distill every thread. Save important sessions: the breakthroughs, the architectural decisions, the hard-won solutions.
For sensitive codebases, review what you're saving. Threads might contain proprietary code or credentials.
## Next Steps [#next-steps]
* [Own Your Knowledge](/docs/use-cases/shared-memory) -> Use any tool without losing context
* [Search Through Time](/docs/use-cases/bi-temporal) -> Find memories from specific time periods
* [Connectors](/docs/integrations) -> Setup guides for each tool
# Own Your Knowledge (/docs/use-cases/shared-memory)
## The Problem [#the-problem]
You told Claude Code about your project architecture last week. Today, you're explaining it again to Cursor. Tomorrow, you'll try the new tool everyone's talking about, and start from scratch.
This isn't a memory problem. It's a lock-in problem. Your knowledge is trapped inside whichever tool you used last.
> "I already explained this. Why do I have to start over in a different tool?"
## The Solution [#the-solution]
Nowledge Mem is a knowledge layer that sits between you and the AI tools you connect to Mem. It captures your insights automatically, brings sessions and memories back into one searchable system, and writes a daily briefing so supported tools can start with richer context.
Use the setup path that matches your tool. The memory model stays the same.
If this is the problem you want to solve first, save one decision in Mem, connect the tool you use most, then ask a second tool about that same topic later. When it can recall the earlier decision, the loop is working.
## How It Works [#how-it-works]
### Connect The Right Way For Each Tool [#connect-the-right-way-for-each-tool-step]
* **Dedicated integrations** for Claude Code, Grok Build, Codex, Gemini CLI, OpenClaw, Hermes Agent, Alma, Cursor, Droid, OpenCode, and Copilot CLI give you the best first-time experience.
* **Reusable workflow packages** cover agent environments that do not have a dedicated package yet.
* **Direct MCP** remains the fallback when a client has no dedicated package.
For many coding agents, the fastest reusable path is still:
```bash
npx skills add nowledge-co/community/nowledge-mem-npx-skills
```
After setup, your agent can read your briefing at session start, search your knowledge mid-task, and preserve durable insights.
### Capture Happens Automatically [#capture-happens-automatically-step]
You don't need to remember to save. Mem captures from multiple channels:
**Browser Extension (Exchange v2):**
The extension monitors your AI chats on supported web AI chat platforms. Insights are captured automatically as you work.
**Session Capture and Sync:**
Native integrations can capture new coding-agent work where the runtime supports hooks. Local import and `nmem t sync` backfill older sessions from disk.
**Timeline Input:**
Type a thought, paste a URL, drop a file. For the times you want to save something specific.
**Manual Commands:**
```
/sum -> Summarize this conversation into memories
/save -> Create the tool's save or handoff action, depending on the integration
```
### Supported Tools Start Informed [#supported-tools-start-informed-step]
Each morning, Background Intelligence writes a Working Memory briefing. Connected tools can load the right briefing for the active space through their own path at session start.
Your agent already knows:
* What you're working on
* Decisions you made recently
* Open questions and contradictions
* How your thinking has evolved
No re-explanation needed. Open Claude Code at 9 AM and it picks up where you left off.
### Switch Tools Freely [#switch-tools-freely-step]
New tool? Connect it to Mem through the best path it supports. Then it can work from the same shared context.
**Example:**
You saved: *"Architecture decision: Using Redis for session management because..."*
Later, in Cursor: *"Help me add session handling"*
Cursor searches your knowledge, finds the Redis decision, applies the same pattern. No re-explanation needed.
## Real Example [#real-example]
**Without Nowledge Mem:**
> You: "Help me implement rate limiting"
>
> Claude: "What kind? Token bucket? Sliding window? What's your use case?"
>
> You: *\[Explains for the 5th time this month]*
**With Nowledge Mem:**
> You: "Help me implement rate limiting"
>
> Claude: *\[Reads your Working Memory briefing, searches your memories]* "Based on your decision last month to use sliding window rate limiting for the payment service, here's an implementation matching your Redis patterns..."
## What Gets Connected [#what-gets-connected]
| Channel | How It Works | What Gets Captured |
| -------------------------------- | ------------------------------ | ---------------------------------------------------------------------- |
| **Native integrations** | Tool-specific package | Working Memory, recall, distill, and the right save path for that tool |
| **Reusable workflow packages** | Shared prompts or skills | Working Memory, search, save, distill |
| **Browser Extension** | Auto-capture from AI chats | Insights from supported web AI chat platforms |
| **Session capture and backfill** | Native hooks plus local import | Claude Code, Cursor, Codex, OpenCode sessions |
| **MCP** | Direct protocol connection | Any MCP-compatible tool |
| **Claude Desktop** | One-click extension | Full integration |
| **Built-in** | Toggle in settings | DeepChat, LobeHub |
## The Compound Effect [#the-compound-effect]
A few weeks in, any new tool you connect already knows how you work. Your preferences persist across tools. Your decisions compound. Every insight you've ever saved is available to every tool you'll ever use.
The value lives in Mem, not in any single tool.
## Next Steps [#next-steps]
* [Never Lose a Session](/docs/use-cases/session-backup) -> Auto-sync and backup AI conversations
* [Search Through Time](/docs/use-cases/bi-temporal) -> Find what you knew when
* [Connectors](/docs/integrations) -> Connect all your tools
# 后台智能 (/docs/zh/advanced-features)
后台智能让 Mem 不只是把内容存下来。
你保存了记忆、对话和文档之后，系统还会继续在后台工作：把相关想法连接起来、找出矛盾、综合出知识结晶，并写出一份你的工具可以读取的每日简报。
一月，你保存了一个使用 PostgreSQL 的决策。七月，你又记录了正在迁移到 CockroachDB。你没有专门回头整理过这件事，但 Mem 会把两者连起来，追踪这段变化。下次你搜索其中任意一个主题时，都能看到这条思路是怎样一路演变过来的。
这些整理发生在后台。你下次打开应用时，相关连接就已经在那里了。
不要一开始就试图验证后台智能的所有能力。更好的第一步是：先积累一些真实内容，然后确认 Mem 至少出现了一个真正有帮助的结果，比如一条相关的晨间简报、一条你自己没主动想到的连接，或一个被指出来的矛盾。
### 打开 AI Now [#打开-ai-now-step]
点击侧边栏中的 **AI Now** 标签，或按 Cmd/Ctrl + 5。
### 开始一个有根据的任务 [#开始一个有根据的任务-step]
先从一个和你已经给过 Mem 的上下文相匹配的任务开始：
> 我做过哪些关于缓存的架构决定？
在相关时，它会使用你的记忆、网络搜索，以及你已经连接并启用的笔记或插件能力来组织答案。
你也可以拖入文件或文件夹进行分析，或让它基于你的知识生成报告。在工作过程中，AI Now 也可以在合适的时候创建或更新记忆。
如果你使用了 [Spaces](/zh/docs/spaces)，AI Now 会跟随应用里当前激活的 space。这样一个 AI Now 会话就可以专注在某个项目或某个 Agent 分区里，而不需要改动整套 Mem 的使用方式。
## 在聊天中引用记忆 [#在聊天中引用记忆]
使用 @ 搜索并在对话中引用特定记忆。
## 深度研究 [#深度研究]
AI Now 可以运行并行子任务，跨多个来源搜索并综合结果。
在 AI Now 聊天界面中点击 研究 切换以启用深度研究。
### 工作原理 [#工作原理]
提出研究问题：
> 研究量子纠错的当前状态
AI Now 将：
1. 搜索你的记忆了解已有知识
2. 从多个角度搜索网络
3. 综合为一个答案
4. 引用来源并附带可靠性指标
## 可选技能 [#可选技能]
技能是针对特定任务的专门能力。
| 技能 | 启用的功能 |
| -------------- | ---------------------- |
| **文档** | Excel/CSV 分析、图表生成、文件操作 |
| **演示文稿创建器** | 幻灯片生成，带实时预览和导出 |
| **旅行规划器** | 交互式行程创建 |
| **Browse Now** | 用真实浏览器完成登录态和交互型网页任务 |
在 **AI Now** → **插件** → **技能** 中启用技能。
### 文件分析 [#文件分析]
将文件或文件夹附加到你的对话中进行即时分析。
发送消息时，AI Now 会先把这些附件复制到当前任务工作区的 `inputs/`
文件夹。智能体读取这份工作区内的副本，也会把新生成的图表、脚本、报告或幻灯片写回同一个任务文件夹。
如果你连接的是远程 Mem 服务器，AI Now 会运行在那台服务器上。请附加服务器能读取到的文件，或者先把文件加入资料库。
在 AI Now 插件中切换 文档 技能以启用数据分析能力。
#### 支持的文件 [#支持的文件]
| 类型 | 扩展名 | AI Now 做什么 |
| -------- | --------------- | -------------- |
| **电子表格** | .xlsx、.xls、.csv | 分析数据、发现模式、生成图表 |
| **文档** | .docx、.doc、.pdf | 总结、提取要点、回答问题 |
| **代码** | .py、.js、.ts 等 | 审查、解释、建议改进 |
#### 示例 [#示例]
1. 点击文件夹图标附加 `sales_q4.xlsx`
2. 问："这个数据中的前 3 个趋势是什么？"
3. AI Now 分析并生成可视化
你也可以附加整个文件夹一次分析多个文件。
拖入文件夹即可分析：
### 演示文稿 [#演示文稿]
AI Now 可以创建带实时预览和编辑的演示文稿。
在 AI Now 插件中切换 演示文稿 技能以启用演示文稿创建能力。
#### 创建幻灯片 [#创建幻灯片]
> 根据我们上面的研究创建一个演示文稿，包括一些图表或图形来支持洞察
AI Now 生成结构清晰、包含图表和洞察的幻灯片。
#### 编辑 [#编辑]
生成后，通过后续请求进行优化：
* "让第三张幻灯片更有视觉效果"
* "添加一张关于客户细分的幻灯片"
* "简化结论"
或者，点击 编辑 按钮编辑演示文稿。
#### 导出 [#导出]
点击 PPTX 按钮下载为 PowerPoint（.pptx）以在其他工具中使用。
### 旅行规划 [#旅行规划]
AI Now 可以创建详细的旅行行程。
在 AI Now 插件中切换 旅行规划器 技能以启用旅行规划能力。
> 规划一个以美食和文化为重点的 5 天东京之旅
AI Now 生成一个交互式逐日行程，包含活动、地点和提示，以你最近的记忆和深度研究作为上下文。
### Browse Now [#browse-now]
在 **AI Now** → **插件** → **技能** 中打开 Browse Now，让 AI Now 在需要时调用你的真实浏览器。
当任务依赖的是你的浏览器会话，而不是普通抓取时，就该打开它。常见场景包括：
* 需要登录态的网站
* 需要点击、输入、滚动或多步操作的页面
* 需要截图或读取渲染后页面内容的任务
* 动态页面很多，普通抓取拿不到真实界面的情况
这项能力只能在本机使用。浏览器桥接运行在 AI Now 所在机器上，不会通过「随处访问 Mem」暴露出去。
完整的设置、边界和命令行示例见 [Browse Now 指南](/zh/docs/browse-now)。
## 插件 [#插件]
通过插件连接你的其他应用。
### 自定义 MCP 服务 [#自定义-mcp-服务]
如果某个工具已经提供 HTTP MCP 地址，可以在 **AI Now** → **插件** → **添加自定义 MCP** 中粘贴服务地址，填入需要的请求头，启用插件后再让 AI Now 使用它。
像 Lemonade 这类本地提供商，聊天模型请在服务商设置里选择 Lemonade；如果还想让 AI Now 调用 Lemonade 暴露的工具，再把它的 MCP 地址单独添加为自定义 MCP。内置 Rust 运行时目前只接入 HTTP MCP，暂不支持 STDIO MCP。
### 内置插件 [#内置插件]
#### Obsidian [#obsidian]
连接你的本地 Obsidian 知识库：
1. 前往 **AI Now** → **插件**
2. 启用 **Obsidian**
3. 设置你的知识库路径
现在 AI Now 可以与你的记忆一起搜索和阅读你的 Obsidian 笔记。
#### Notion [#notion]
连接你的 Notion 工作区：
1. 前往 **AI Now** → **插件**
2. 启用 **Notion**
3. 点击 **连接** 并在浏览器中授权
AI Now 现在可以搜索你的 Notion 页面和数据库。
#### Apple Notes (macOS) [#apple-notes-macos]
在 macOS 上，AI Now 可以搜索和阅读你的 Apple Notes：
1. 前往 **AI Now** → **插件**
2. 启用 **Apple Notes**
3. 在提示时授予权限
无需设置路径或同步，直接以只读方式读取系统数据库。
### 自定义 MCP 插件 [#自定义-mcp-插件]
AI Now 支持模型上下文协议（MCP）用于自定义集成。
### 从 Alma 插件市场安装 [#从-alma-插件市场安装-step]
在 Alma 中打开**设置** → **插件** → **市场**，搜索 **Nowledge Mem**，点击**安装**。
### 如需请重启 Alma [#如需请重启-alma-step]
### 可选：启用 Alma Skill [#可选启用-alma-skill-step]
不做这一步插件也能工作：工具、自动回忆和对话同步都由插件负责。如果你使用 Alma 的 **设置 → Skills** 页面，先看看是否出现随插件附带的 `nowledge-mem` Skill；如果出现，建议启用。它会提醒 Alma 什么时候读取 Context Bundle、搜索过往工作、查看来源对话，以及保存值得长期保留的决策。
如果安装插件后没有看到这个 Skill，可以复制到 Alma 的个人 Skills 目录，然后刷新 Skills：
```bash
mkdir -p ~/.config/alma/skills/nowledge-mem
cp ~/.config/alma/plugins/nowledge-mem/skills/nowledge-mem/SKILL.md \
~/.config/alma/skills/nowledge-mem/SKILL.md
```
### 在新线程里验证 [#在新线程里验证-step]
请 Alma 调用状态工具：
```text
请使用 Nowledge Mem status 工具，告诉我服务器是否已连接。
```
然后发送一条普通短消息，等待几秒、切换线程，或正常退出 Alma。该对话应出现在 Nowledge Mem 的**对话**页面，来源为 `alma`。
### 让 ChatGPT 使用 Mem [#让-chatgpt-使用-mem-step]
在 ChatGPT 网页版或桌面版里输入 `@Nowledge Mem`，然后让它搜索 Mem，例如："Search my Mem for the project decision about the database migration."
目前创建自定义 connector 需要从 ChatGPT 网页设置进入。添加完成后，同一个
ChatGPT 账号可以在桌面版里通过 `@Nowledge Mem` 调用它。
## 应该用哪条路径？ [#应该用哪条路径]
| 目标 | 使用 |
| ------------------------------------- | ------------------------------------------------ |
| 把有价值的 ChatGPT 对话保存进 Mem | 浏览器扩展 |
| 让 ChatGPT 网页版或桌面版在对话中搜索 Mem | Remote MCP over OAuth |
| 导入多年 ChatGPT 历史记录 | [导入已有对话](/zh/docs/import-existing-conversations) |
| 没有官方全量导出的 ChatGPT Team / Business 旧历史 | 用你信任的工具导出到本地，再用 `nmem` 导入 |
## 相关 [#相关]
* [连接总览](/zh/docs/integrations)
* [Access Anywhere](/zh/docs/remote-access)
* [浏览器扩展](/zh/docs/integrations/browser-extension)
* [导入已有对话](/zh/docs/import-existing-conversations)
# Claude Code (/docs/zh/integrations/claude-code)
把这行交给你的智能体。它应该先使用统一安装指南；这一页保留为行为说明和排障参考：
```text
读取 https://mem.nowledge.co/SKILL.md，按其中说明为 Claude Code 安装或更新 Nowledge Mem。用 nmem status 和 Working Memory 检查验证结果，并总结你改了什么。
```
```bash title="一键安装"
claude plugin marketplace add https://github.com/nowledge-co/community && claude plugin install nowledge-mem@nowledge-community
```
Claude Code 支持插件，一次安装即可获得内置自主行为，无需配置系统提示或 MCP。
智能体会自动搜索你已经知道的内容，并在正确的时机保存值得留下的东西，无需你手动触发。
安装好插件、确认 `nmem` 可用，然后开一个新的 Claude Code 会话。只要你能看到工作记忆简报在开局被读取，或者 `/search` / `/save` 无需额外配置就能工作，这条路径就已经接通了。
## 开始之前 [#开始之前]
* Nowledge Mem 已在本地运行（[安装指南](/zh/docs/installation)），或你已经有可访问的远程 Mem 服务
* 已安装 Claude Code
## 设置 [#设置]
## 相关 [#相关]
* [连接总览](/zh/docs/integrations): 原生连接、复用包、MCP 与浏览器捕获
* [Claude Code](/zh/docs/integrations/claude-code) · [Claude Desktop](/zh/docs/integrations/claude-desktop) · [Codex](/zh/docs/integrations/codex-cli) · [Alma](/zh/docs/integrations/alma) · [OpenClaw](/zh/docs/integrations/openclaw) · [Raycast](/zh/docs/integrations/raycast)
# Paseo (/docs/zh/integrations/paseo)
Paseo 会在你的电脑上启动 Claude Code、Codex、Copilot、OpenCode、Pi、OMP 等编程 agent。
Nowledge Mem 应该接在这些被启动的 AI 工具上。Paseo 是编排层：它决定哪个 worker 运行；MCP、hook 和会话文件仍然属于被启动的工具。
Paseo 自己的 MCP 工具用于编排，比如创建 agent 或 worktree。你可以继续使用它们，但它们不能替代被启动 AI 工具里的 Nowledge Mem 连接，也不会自动把每段 transcript 都捕获进 Mem。
## 你需要准备什么 [#你需要准备什么]
1. Nowledge Mem 已经在 Paseo 启动 agent 的那台机器上运行。
2. Paseo 会启动的 AI 工具已经连接到 Mem，例如 [Codex](/zh/docs/integrations/codex-cli)、[Claude Code](/zh/docs/integrations/claude-code)、[OpenCode](/zh/docs/integrations/opencode)、[Pi](/zh/docs/integrations/pi) 或 [OMP](/zh/docs/integrations/omp)。
3. 你知道哪些 Paseo agent 是长期角色，哪些只是一次性任务。
## 第一步怎么做 [#第一步怎么做]
先连接被 Paseo 启动的 AI 工具。比如 Paseo 启动 Codex，就先安装并验证 Codex 连接；启动 Pi，就先安装并验证 Pi 包；启动 OMP，就先安装并验证 OMP 插件。
如果某个 Paseo agent 是稳定角色，先创建一个 Mem AI 身份：
```bash
nmem agents upsert cindy \
--name "Cindy" \
--default-space onboarding \
--instructions "Help with onboarding. Explain one step at a time."
```
然后把这个身份传给它启动的子运行时：
```bash
NMEM_AGENT_ID=cindy
```
一次性 advisor、短期实现 agent、通用 provider preset 不需要设置 `NMEM_AGENT_ID`。它们仍然可以通过子工具的 Mem 连接使用记忆，只是不需要一个长期身份。
## 不要把来源写成 Paseo [#不要把来源写成-paseo]
不要把所有子会话都标成 `paseo`。
`source_app` 应该使用真正启动的 AI 工具：
* Paseo 启动 Codex：`source_app=codex`
* Paseo 启动 Claude Code：`source_app=claude-code`
* Paseo 启动 OpenCode：`source_app=opencode`
* Paseo 启动 Pi：`source_app=pi`
* Paseo 启动 OMP：`source_app=omp`
这样，线程筛选、图标和捕获路径才是正确的。Mem AI 身份表示这个 worker 的长期角色；source app 表示实际产生会话的工具。
## 哪些内容会同步 [#哪些内容会同步]
受支持的子工具会话有两种同步方式。
### 使用过程中 [#使用过程中]
工作中新会话的自动捕获来自被启动 AI 工具里安装的连接。
如果 Paseo 启动 Codex，就安装 Codex 连接；如果启动 Claude Code，就安装 Claude Code 连接；如果启动 OpenCode、Pi 或 OMP，就安装对应包。Paseo 可以运行这些工具，但 Paseo 自己目前没有提供一个每次 child turn 结束后触发 Mem 的 hook。
### 导入旧的 Paseo Agent [#导入旧的-paseo-agent]
旧的 Paseo 管理会话可以从 Paseo 本地 agent registry 导入：
```bash
nmem t sync --from paseo --all-projects --apply
```
这个命令会读取 Paseo 的 agent 记录，找到受支持的子工具会话，再导入真正的子工具 transcript。导入后的线程仍保留子工具来源，例如 `codex`、`claude-code`、`opencode`、`pi` 或 `omp`；不会被统一标成 `paseo`。
这个导入可以安全重复运行。Paseo-guided sync 使用和子工具直接同步一样的 child thread id，所以一个通过 Paseo 导入的 Codex 会话仍会进入同一个 `codex-*` 线程，而不是再创建一份 `paseo-*` 副本。
Paseo 的终端状态、定时任务和聊天室是另一层数据。只有当 Paseo 未来为这些表面提供消息级 transcript export、API 或 hook 时，Nowledge Mem 才能直接导入它们。
## 怎么确认成功 [#怎么确认成功]
在 Paseo 启动的 AI 工具里运行：
```bash
nmem --json context --source-app codex
```
把 `codex` 换成实际被启动的工具。如果子运行时收到了 `NMEM_AGENT_ID=cindy`，Context Bundle 应该显示 Cindy 的身份和默认 Space。
如果你在普通终端里检查，就显式传入身份：
```bash
nmem --json context --agent-id cindy --source-app codex
```
## 下一步 [#下一步]
* [Codex](/zh/docs/integrations/codex-cli)
* [Claude Code](/zh/docs/integrations/claude-code)
* [OpenCode](/zh/docs/integrations/opencode)
* [Pi](/zh/docs/integrations/pi)
* [OMP](/zh/docs/integrations/omp)
* [自定义连接行为](/zh/docs/integrations/customize-behavior)
# Pi × Nowledge Mem (/docs/zh/integrations/pi)
把这行交给你的智能体。它应该先使用统一安装指南；这一页保留为行为说明和排障参考：
```text
读取 https://mem.nowledge.co/SKILL.md，按其中说明为 Pi 安装或更新 Nowledge Mem。用 nmem status 和 Context Bundle 或 Working Memory 检查验证结果，并总结你改了什么。
```
```bash title="一键安装"
pi install npm:nowledge-mem-pi
```
Pi 是一款精简的终端编程智能体。Nowledge Mem 为它补充跨工具知识：来自 Claude Code、Cursor、Codex 等工具的决策和经验，在 Pi 中即刻可用。安装插件包之后，Pi 中完成的会话也会同步回 Nowledge Mem，之后你可以在其他工具里搜索到这些对话。
插件包现在有两条自动路径：Pi 会在会话启动时收到 Context Bundle 或 Working Memory，完成后的 Pi 对话也会同步成可搜索的 Threads。Skills 仍然用于会话中的检索、保存决策和显式交接。
## 准备工作 [#准备工作]
* **Nowledge Mem** 已在本地运行（[安装指南](/zh/docs/installation)）
* **Pi** 已安装
* **`nmem` CLI** 已在 PATH 中。在 Nowledge Mem 中前往 **设置 → 偏好设置 → 开发者工具 → 安装 CLI**，或执行 `pip install nmem-cli`
```bash
nmem status # 确认 Nowledge Mem 正在运行
pi --version # 确认 Pi 可用
```
## 安装 [#安装]
### 安装插件包 [#安装插件包-step]
```bash
pi install npm:nowledge-mem-pi
```
### 验证集成 [#验证集成-step]
让 Pi 检查与 Nowledge Mem 的连接：
```
Nowledge Mem 连上了吗？运行一下 status 技能。
```
你应该会看到连接信息，以及服务器可达的确认。看到这些就说明通了：Pi 现在能用上你在其他工具里积累的知识。
安装或更新后，重新开启一个 Pi 会话。Pi 应该已经在系统上下文里拿到 Nowledge Mem 的启动上下文，不需要再为了知道今日 Context Bundle 而主动运行 `read-working-memory` 技能。
## 更新 [#更新]
```bash
pi update
```
更新后请重启 Pi，让 Nowledge Mem 扩展重新加载。
## 导入旧会话 [#导入旧会话]
自动同步会从安装插件包之后开始。如果你想把更早的 Pi 会话也导入 Nowledge Mem，可以运行一次历史导入。
先预览：
```bash
nmem t sync --from pi --limit 20
```
确认无误后再导入：
```bash
nmem t sync --from pi --apply
```
这个命令会读取本机的 Pi 会话文件，并写入 CLI 或扩展当前配置的 Mem 服务器。它可以重复运行：Pi 会话 ID 会变成稳定的 Thread ID，重复消息会被自动去重。
常用过滤：
```bash
nmem t sync --from pi --session-dir ~/.pi/agent/sessions --limit 20
nmem t sync --from pi --space work --apply
```
传入 `--session-dir` 时，只扫描这个目录。不传时，命令会使用 Pi 的默认会话目录。
如果你安装的 `nmem` 还没有 `t sync`，可以先用插件包自带的备用命令：
```bash
npx -p nowledge-mem-pi nowledge-mem-pi-sync --apply
```
## 安全地自定义 [#安全地自定义]
优先使用项目自己的 `AGENTS.md`，而不是去改安装后的包缓存。
* 如果你希望 Pi 在这个仓库里更主动地检索或保存，就把包里的行为指引合并进项目 `AGENTS.md`
* 把包文件保留为默认值，这样升级时不会把你的微调冲掉
Pi 目前没有单独的持久 override 文件，最稳妥的入口就是项目级行为指引。完整对照表见 [安全地自定义连接行为](/zh/docs/integrations/customize-behavior)。
## 你能做什么 [#你能做什么]
**让 Pi 对话自动进入 Threads**
插件包包含一个原生 Pi 扩展。安装之后，每轮对话完成后、切换会话、压缩上下文或退出时，它会把当前 Pi 会话分支同步成 Nowledge Mem 里的 `pi` 对话。
**在 Pi 中查找其他工具的知识**
问一句"数据库方案之前定了什么？"，Pi 就可以去搜索你在 Claude Code 中做过的决策、在 ChatGPT 中获得的洞察、在 Cursor 中留下的笔记，而不仅仅是当前会话。
**保存知识，全局可用**
当你在 Pi 中得出结论时，可以让 `distill-memory` 把它存下来。这样你下次打开 Claude Code、Cursor 或 ChatGPT 时都还能找到。
**会话一开始就有上下文**
扩展会优先注入 Context Bundle，必要时回退到 Working Memory。只要你的 Mem 服务支持，Pi 启动时就会拿到 owner identity、AI Identity、当前 scope、Rules 和今日重点。
项目 `AGENTS.md` 仍然有价值，但它负责的是行为偏好，而不是启动上下文：你可以用它让 Pi 在某个仓库里更主动地检索和保存。
**创建可恢复的交接**
自动同步会保留对话本身。当你明确让 Pi 保存交接时，它还会额外生成一份结构化摘要，方便你到 Claude Code 或其他工具里继续接着做。
## 技能一览 [#技能一览]
| 技能 | 说明 |
| --------------------- | ----------------------------------- |
| `read-working-memory` | 读取今日 Working Memory：关注领域、优先事项、近期动态。 |
| `search-memory` | 跨工具搜索知识，支持标签和日期过滤。 |
| `distill-memory` | 保存一个决策、洞察或偏好，让任何工具都能找到。 |
| `save-thread` | 在你明确需要时，额外生成一份结构化交接摘要。 |
| `status` | 连接状态与配置诊断。 |
## 配置 [#配置]
本地使用无需配置。
| 环境变量 | 默认值 | 说明 |
| -------------------- | -------- | -------------------------- |
| `NMEM_API_URL` | *(本地)* | 远程 Nowledge Mem 服务器地址 |
| `NMEM_API_KEY` | *(无)* | 远程访问的 API 密钥 |
| `NMEM_SPACE` | *(默认空间)* | 这个 Pi 进程使用的可选记忆空间 |
| `NMEM_AGENT_ID` | *(无)* | 多智能体编排时使用的 Mem AI Identity |
| `NMEM_HOST_AGENT_ID` | *(无)* | 高级外部别名 |
如果你想用一套持久化的共享配置，先在这台机器上执行 `nmem config client ...`。Pi 扩展会读取与 CLI 相同的 `~/.nowledge-mem/config.json`。如果只是临时覆盖，环境变量的优先级仍然更高。
### 远程访问 [#远程访问]
```bash
nmem config client set url https://your-server
nmem config client set api-key your-key
```
参见 [随处访问 Mem](/zh/docs/remote-access)。
## 常见问题 [#常见问题]
\*\*找不到 nmem 命令。\*\*执行 `pip install nmem-cli`，然后运行 `nmem status` 确认连接正常。
\*\*服务器无响应。\*\*启动 Nowledge Mem 桌面应用，或用 `nmem status` 检查诊断信息。
\*\*技能未加载。\*\*用 `pi list` 确认插件已安装。如果看不到 `nowledge-mem-pi`，请重新安装：`pi install npm:nowledge-mem-pi`。
\*\*Pi 对话没有出现在 Threads。\*\*安装或更新后先重启 Pi，然后进行一次包含用户消息和助手回复的短对话，再检查：
```bash
nmem t list --source pi -n 5
```
扩展会刻意跳过只有一条消息的会话，避免 `/new` 或空会话制造噪音。
\*\*旧 Pi 对话没有出现。\*\*自动同步无法看到安装插件包之前已经发生的会话。请用 `nmem t sync --from pi` 预览并导入历史 Pi 会话文件。
## 相关 [#相关]
* [连接总览](/zh/docs/integrations)
* [Claude Code](/zh/docs/integrations/claude-code) · [OpenCode](/zh/docs/integrations/opencode) · [Hermes Agent](/zh/docs/integrations/hermes) · [OpenClaw](/zh/docs/integrations/openclaw) · [Alma](/zh/docs/integrations/alma) · [Bub](/zh/docs/integrations/bub)
* 插件源码：[nowledge-mem-pi-package](https://github.com/nowledge-co/community/tree/main/nowledge-mem-pi-package)
# Proma × Nowledge Mem (/docs/zh/integrations/proma)
如果你想让智能体帮你配置，可以把这句话交给它：
```text
读取 https://mem.nowledge.co/SKILL.md，按其中说明为 Proma 安装或更新 Nowledge Mem。用 nmem status、启动上下文和 Proma 线程保存结果验证，并总结你改了什么。
```
Proma 接入 Nowledge Mem 后，你会得到这些：Proma 可以在需要时搜索记忆、保存长期知识、浏览 Mem；通过生命周期 hooks，Proma 对话会自动存成 Mem 线程；每次新会话开始前，当前的 Mem 上下文会写进工作区 `CLAUDE.md`，让智能体一上来就知道重要背景。
Proma v0.13.0 及之后版本已经在「Memory」设置里加入 Nowledge Mem 卡片。第一次配置时，优先从那里复制配置提示词，贴到 Proma Agent 模式里执行。这页文档保留完整文件路径、更新方式和验证步骤，方便你检查或修复配置。
打开一个新的 Proma 会话，问 What was I working on?。然后发送一条带有独特短语的消息，等 Proma 回复完成后运行 nmem t search "那段短语" --source proma。你应该能在 Mem 里看到这条 Proma 线程。
## 开始之前 [#开始之前]
* Nowledge Mem 已在本地运行，或你有可访问的远程 Mem 服务。
* 已安装 Proma。
* 本机有 Python 3.9+，命令名为 `python3`。
* `nmem` 能在终端里正常运行。
```bash
nmem status
```
如果找不到 `nmem`，可以从 Mem 桌面应用的开发者工具安装 CLI，或运行：
```bash
pip install nmem-cli
```
## 安装 [#安装]
如果你使用 Proma v0.13.0 或更新版本，可以先打开 **Proma 设置 → Memory → Nowledge Mem**，复制配置提示词并粘贴到 Proma Agent 模式。下面的手动步骤与这条提示词使用的是同一套配置，只是展开成了可检查的版本。
下面示例使用 Proma 的 `default` 工作区。如果你的工作区不是这个名字，把所有 `default` 替换成 `~/.proma/agent-workspaces/` 下面对应的目录名。
如果你的系统只有 `python` 命令，请把下面 hook 命令里的 `python3` 替换成 `python`。
