09. devmemory show

Renders and prints a markdown memory file beautifully in the terminal using ANSI color formatting. Reading raw markdown files in a shell is painful — the show command parses markdown syntax and outputs a color-styled, wrapped, human-readable rendering directly in your console.

Syntax

devmemory show <target>

Arguments

Target Types

The <target> argument accepts five different input types. DevMemory resolves them in this priority order:

1. Build Index (Number)

Pass a number to render a specific build log. DevMemory zero-pads the number to 3 digits and looks for a matching build-XXX-*.md file in .devmemory/.

# All three of these are equivalent — they render build-005-*.md
devmemory show 5
devmemory show 05
devmemory show 005

How it resolves: The CLI takes your number (e.g., 5), formats it as 005, and runs a glob search for .devmemory/build-005-*.md. If found, it renders that file. If no file matches, it exits with: Error: Build index 005 not found in .devmemory/.

2. "brain" — Project Brain

Renders the .devmemory/project-brain.md file — the living, evolving description of your entire codebase including tech stack, features, architecture overview, key files, and known issues.

devmemory show brain

3. "changelog" or "log" — Release Changelog

Renders the .devmemory/changelog.md file — a chronological log of all recorded changes, organized by build.

# Both of these are equivalent
devmemory show changelog
devmemory show log

4. "context" — Full Project Context

Renders the .devmemory/FULL_PROJECT_CONTEXT.md file — a single aggregated document combining the project brain, changelog, and complete build timeline table. This is the file you copy-paste into external AI prompts.

devmemory show context

5. Filename or File Path

You can also pass a filename within .devmemory/ or any absolute/relative file path to render any arbitrary markdown file.

# Render a specific file inside .devmemory/
devmemory show build-003-jwt-login-validation.md

# Render any markdown file by path
devmemory show ./README.md
devmemory show /absolute/path/to/notes.md

Renderer Features

• ANSI color formatting — headers, bold text, code blocks, and lists are styled with terminal colors.
• Dynamic text wrapping — text wraps naturally to fit your terminal width without truncation.
• Code block borders — code and Mermaid blocks are rendered with a vertical left border (│) for visual separation.
• No external dependencies — the renderer is a pure Python implementation with no third-party terminal libraries.

10. devmemory context

Manually regenerates the .devmemory/FULL_PROJECT_CONTEXT.md file. This is a utility command for when you need to rebuild the aggregated context without recording a new build.

Syntax

devmemory context

No flags or arguments.

What It Does

Aggregates three data sources into a single markdown file:

1. Project Brain (project-brain.md) — the living codebase description.
2. Build Timeline (timeline.json) — a structured table of all builds with their IDs, titles, timestamps, and modified files.
3. Metadata — a note explaining the file is auto-generated.

The resulting FULL_PROJECT_CONTEXT.md is designed to be copy-pasted into external AI chat prompts (Cursor, Claude, Gemini, ChatGPT) to instantly reload repository context and give the AI full awareness of your project's history and structure.

When to Use

• If you manually edited project-brain.md or changelog.md and want the context file to reflect those changes.
• If the context file was accidentally deleted or corrupted.
• Before sharing the context file with a team member or pasting it into an AI prompt.

Example

$ devmemory context
Successfully regenerated .devmemory/FULL_PROJECT_CONTEXT.md

11. devmemory setup-ollama

Automatically installs a local portable instance of Ollama, starts the background service on port 11434, and pulls the lightweight qwen2.5-coder:0.5b model. This allows a completely automated, zero-config setup for running DevMemory offline and credit-free.

Syntax

devmemory setup-ollama [OPTIONS]

Options

• --model <model-name> — The Ollama model to pull. Defaults to qwen2.5-coder:0.5b.

What It Does

1. OS Detection — Automatically detects whether you are running macOS, Windows, or Linux.
2. Download & Install — If Ollama is not in your system PATH, downloads the official, platform-specific portable binary or archive and extracts it cleanly under ~/.devmemory/bin/.
3. Detached Background Service — Launches the background process (ollama serve) silently and polls the local endpoint until it responds on port 11434.
4. Interactive Model Pulling — Queries Ollama if the target model is already pulled. If not, pulls the model while streaming the download progress bar directly to your terminal.

curl -fsSL https://ollama.com/install.sh | sh

irm https://ollama.com/install.ps1 | iex

When to Use

• When initializing DevMemory with the Ollama local provider for the first time.
• To pull new models or pre-download dependencies for complete offline usage.
• To fix stopped background instances of Ollama.

Example

$ devmemory setup-ollama
=== DevMemory Local Ollama Setup ===
[DevMemory] Downloading Ollama for darwin...
[DevMemory] From: https://github.com/ollama/ollama/releases/latest/download/ollama-darwin.tgz
[DevMemory] Extracting and installing Ollama...
[DevMemory] Ollama successfully installed to /Users/username/.devmemory/bin/ollama!
[DevMemory] Starting Ollama background service...
[DevMemory] Waiting for Ollama service to start (max 15 seconds)...
[DevMemory] Ollama service is running and ready!
[DevMemory] Pulling model qwen2.5-coder:0.5b. This may take a few minutes...
pulling 2ef70d8a5462... 100% ▕██████████████████████████████████████▏ 368 MB
pulling 1f7df2b1ff20... 100% ▕██████████████████████████████████████▏  15 KB
[DevMemory] Model qwen2.5-coder:0.5b successfully pulled!

Ollama and model are fully set up and ready to use!

12. devmemory terminate

Stops and removes the background daemon, preventing it from auto-starting on system reboot. This is useful when you want to completely disable DevMemory monitoring for a project or clean up system resources.

Syntax

devmemory terminate

No flags or arguments. Must be run from the root directory of your initialized project.

What It Does

Unregisters and stops the daemon service that was created during devmemory init:

• macOS — Unloads and removes the LaunchAgent plist from ~/Library/LaunchAgents/com.devmemory.watcher.<hash>.plist. Kills any running daemon process.
• Linux — Stops and disables the systemd user service from ~/.config/systemd/user/devmemory-watcher-<hash>.service. Kills any running daemon process.
• Windows — Removes the startup batch file from the Windows Startup folder and terminates the daemon process.

When to Use

• When you want to stop monitoring a project permanently.
• Before uninstalling DevMemory globally or deleting a project directory.
• To free up system resources on machines with limited memory.
• If the daemon becomes unresponsive or you want to manually clean it up.

Example

$ devmemory terminate
[DevMemory] Stopping background daemon...
[DevMemory] Daemon successfully terminated and removed from system startup.

13. devmemory status

Displays the current configuration settings, active LLM provider, target model, and details of the background watcher daemon. On macOS and Linux, it actively queries the OS service managers (launchd or systemd) to verify the process status (PID and running/stopped state) and lists the platform-specific commands to manage the service.

Syntax

devmemory status

No flags or arguments. Must be run from the root directory of your initialized project.

What It Does

• Configuration Summary — Prints the current project settings (Provider, Model, Base URL, Cooldown period).
• Active Process Check — Verifies if the daemon is loaded and running under the current user session.
• Platform Management Instructions — Lists the exact terminal commands to manually start, stop, restart, or view standard logs for the daemon on your current operating system.

Example

$ devmemory status
=== DevMemory AI Status ===
Project Path: /Users/username/my-project
Provider:     ollama
Model:        qwen2.5-coder:0.5b
Base URL:     http://localhost:11434
Cooldown:     15s

--- Background Daemon Information ---
Launchd Label: com.devmemory.watcher.c4472d443f75
Status:        Active (PID: 75874)

Management Commands:
  Start:   launchctl load ~/Library/LaunchAgents/com.devmemory.watcher.c4472d443f75.plist
  Stop:    launchctl unload ~/Library/LaunchAgents/com.devmemory.watcher.c4472d443f75.plist
  Logs:    devmemory logs

14. devmemory logs

Reads and outputs the recent log entries of the background watcher daemon directly from the local .devmemory/watcher.log file. This is highly useful for troubleshooting connectivity errors, verifying watcher events, or checking the progress of the multi-agent analysis.

Syntax

devmemory logs [OPTIONS]

Options

• --lines, -n <number> — The number of lines to display from the tail of the log file. Defaults to 50.

Example

$ devmemory logs -n 5
[2026-06-12T06:09:41.011Z] [DevMemory Watcher Event] change on index.html
[2026-06-12T06:09:41.012Z] [DevMemory Watcher Change Detected] Relative path: index.html
[2026-06-12T06:09:56.022Z] [DevMemory] Detected stabilized changes in: index.html
[2026-06-12T06:09:56.023Z] [DevMemory] Recording changes automatically in background...
[2026-06-12T06:10:04.550Z] [DevMemory] Memory successfully updated!

15. Rate Limiting

DevMemory AI features an autonomous, customizable session rate limit system designed to safeguard your local machine and API budgets.

Why Rate Limiting is Necessary

• Infinite Loops in Small Models — Smaller local LLMs (like qwen2.5-coder:0.5b) are prone to repetitive generation bugs. If the model gets caught in a loop, it could write infinitely to the build files, bloating your storage and keeping your CPU pegged at 100%. Rate limiting forces a safety break.
• API Cost Protection — Prevents background watch events from running wild and making hundreds of expensive cloud API requests (e.g., using Gemini, Claude, or OpenAI), protecting you from unexpected bills.
• System Resource Conservation — Rather than allowing a stuck watcher to continue consuming background CPU and API credits, DevMemory breaks early and goes dormant.

How It Works

• Session Threshold — During devmemory config, you can define a maximum number of API calls permitted per session (leave it blank for unlimited).
• One-Time Desktop Alert — When the threshold is reached, DevMemory triggers a native OS popup warning on your screen (using AppleScript on macOS, PowerShell on Windows, or zenity on Linux) to notify you immediately. To prevent notification spam, this popup is shown only once per configuration (tracked via .devmemory/rate_limit_warned).
• Graceful Service Kill — The background daemon is automatically stopped (equivalent to running devmemory terminate) to ensure it doesn't try to auto-restart and hit the limit again.
• Warning Reset — Once you run devmemory config or devmemory init to adjust your limits, the warning state is reset.

16. Multi-Agent Pipeline

Every time DevMemory records a build (via record or watch), it orchestrates a team of 7 specialized AI sub-agents. Each agent receives the git diff and relevant context, performs a focused analysis, and returns structured output. The first 5 agents produce the build memory file content; the final 2 agents update the living project brain and changelog.

Here is the execution order and what each agent does:

1. Summary Agent

Input: Git diff + original developer prompt.

Output: JSON containing a URL slug, title, summary paragraph, bullet-point changes, and list of files changed.

Purpose: Provides the high-level "what happened" overview. The slug is used to name the build file (e.g., build-003-jwt-login-validation.md).

2. Architecture Agent

Input: Git diff + file/folder context.

Output: JSON containing a Mermaid.js flowchart or sequence diagram, an architectural explanation, and a list of risks/tradeoffs.

Purpose: Creates a visual representation of how components interact after the change. Helps future developers understand data flow at a glance.

3. Regeneration Agent

Input: Original prompt + summary data + architecture data.

Output: A plain-text prompt (not JSON) that a developer can copy-paste into any AI coding tool to recreate the exact same feature from scratch.

Purpose: Makes every feature reproducible. If you ever need to rebuild a feature in a different codebase, the regeneration prompt has everything the AI needs.

4. Validation Agent

Input: Git diff + summary data.

Output: JSON containing test cases, manual verification steps, and mock inputs/payloads.

Purpose: Produces a testing checklist. Developers can use the test cases for unit tests and the mock inputs (e.g., curl commands) for integration testing.

5. Security Agent

Input: Git diff + file summary.

Output: JSON containing security concerns, identified vulnerabilities, and actionable recommendations.

Purpose: Audits every code change for hardcoded API keys, SQL injection risks, missing input sanitization, insecure defaults, and other security issues.

6. Brain Agent

Input: Current project-brain.md content + new build markdown.

Output: The updated project-brain.md content (full markdown, not JSON).

Purpose: Merges new features, files, and architectural changes into the living project brain. Keeps the tech stack, features list, and key files index up to date.

7. Changelog Agent

Input: Current changelog.md + new build markdown.

Output: The updated changelog.md content (full markdown).

Purpose: Appends or merges the new build details into the chronological changelog.

17. File Structure

After initialization and a few recorded builds, your .devmemory/ directory will look like this:

your-project/
├── .devmemory/
│   ├── config.json                  # Your API config (gitignored)
│   ├── project-brain.md             # Living codebase description
│   ├── changelog.md                 # Chronological change log
│   ├── timeline.json                # Build metadata index
│   ├── watcher_state.json           # Watcher connection state cache
│   ├── FULL_PROJECT_CONTEXT.md      # Aggregated context for AI prompts
│   ├── build-001-initial-setup.md   # Build #1 memory
│   ├── build-002-add-auth.md        # Build #2 memory
│   ├── build-003-fix-database.md    # Build #3 memory
│   └── ...
├── .gitignore                       # Contains .devmemory/config.json
└── (your project files)

File Descriptions

Build Memory File Contents

Each build-XXX-slug.md file contains these sections:

• Original Prompt — the developer intent that triggered this build.
• Summary — high-level paragraph of what changed.
• Files Changed — list of modified/added files.
• Architecture — Mermaid.js diagram + data flow explanation.
• Risks & Tradeoffs — potential architectural concerns.
• Security & Vulnerability Check — concerns, vulnerabilities, and recommendations.
• Test & Validation Plan — test cases, verification steps, and mock inputs.
• Regeneration Prompt — a complete prompt to recreate this feature from scratch.

18. Environment Variables

DevMemory supports environment variable overrides for API keys. If a matching environment variable is set, it takes priority over the key stored in config.json. This is useful for CI/CD environments or when you don't want to store keys on disk.

Supported Variables

How It Works

When DevMemory loads its configuration, it checks if the environment variable for the active provider is set. If found, it uses that value instead of the api_key field in config.json. The config wizard also detects existing environment variables and asks if you want to use them during setup.

Example

# Set the key in your shell profile (e.g. ~/.zshrc)
export GEMINI_API_KEY="your-api-key-here"

# Now DevMemory will use this key automatically
# even if config.json has a different or empty key
devmemory record -p "Add user dashboard"

19. Supported Providers

DevMemory AI is provider-agnostic. You can use it with cloud APIs or run it completely free and offline using a local model. Here is the full list of supported providers, their default models, and endpoints: