Agentmemory Local Workbench

Local-first helper scripts, UI/UX notes, and safe extension scaffolding for running an Agentmemory viewer on your own machine.

This repo is intentionally small. It does not contain your memory database, local conversations, screenshots, profile facts, or third-party source repos.

It is based on UI/UX customization work around the open-source rohitg00/agentmemory project. It is not an official fork; it is a clean local workbench for reusable scripts, documentation, and upstream-ready change notes.

Why This Exists

Agentmemory can store useful context from coding-agent sessions, but the default local setup can feel a little hidden:

• you need a repeatable way to start the service;
• you need a quick way to open the viewer;
• you may want to import local Codex sessions;
• you need clear privacy boundaries before putting anything on GitHub;
• you may want a more user-friendly memory viewer for non-technical use.

This workbench collects those pieces without bundling private data.

What You Get

• One-command local startup for Agentmemory.
• A browser launcher for the dashboard.
• A Codex JSONL importer with basic secret redaction.
• Product notes for a quieter Chinese memory-viewer UI.
• Patch notes for local viewer improvements, including identity profile display and editable memories.
• Upstream structure notes that explain where these UI/UX changes belong in the original project.
• A privacy scanner for checking that personal local data is not accidentally committed.
• A visible LOG.md for progress, checks, pushes, and errors.

Quick Start

Install or expose Agentmemory first, then run:

npm run start

Default ports:

Service	URL
REST API	http://127.0.0.1:3111
Streams	http://127.0.0.1:3112
Viewer	http://127.0.0.1:3113

Open a specific viewer tab:

node tools/open-agentmemory.mjs '#memories'
node tools/open-agentmemory.mjs '#sessions'

Restart the local service:

npm run restart

Requirements

• Node.js 20 or newer.
• Agentmemory installed globally, or a direct CLI path passed through AGENTMEMORY_CLI.

Example with an explicit CLI path:

AGENTMEMORY_CLI=/path/to/@agentmemory/agentmemory/dist/cli.mjs npm run start

Use a different port range:

AGENTMEMORY_URL=http://127.0.0.1:3211 npm run start

Import Local Codex Sessions

Import recent Codex JSONL sessions into the local Agentmemory service:

npm run import:codex

Useful options:

CODEX_IMPORT_LIMIT=50 npm run import:codex
CODEX_IMPORT_CWD_FILTER=/path/to/project npm run import:codex
node tools/import-codex-to-agentmemory.mjs /path/to/jsonl/folder

The importer reads from your local $HOME/.codex folders by default. It posts only to the local service configured by AGENTMEMORY_URL.

Viewer Improvements Documented Here

See docs/viewer-patches.md for the implementation notes.

Current local patch themes:

• local Codex and Claude session discovery;
• filtering broken session rows;
• grouping recent sessions by folder;
• explaining token-savings estimates;
• promoting identity memories into a profile card;
• editing memories from the viewer.

See docs/product-design-spec.md for the product direction.

See docs/upstream-structure.md for how the original Agentmemory project is organized.

See docs/apply-local-uiux.md for how these local UI/UX changes should be moved into a real Agentmemory fork or pull request.

See docs/roadmap.md for the next steps.

See LOG.md for the running project log.

Privacy Boundary

This repo is meant to be safe to publish because it excludes private runtime content.

Do not commit:

• data/;
• local session .jsonl files;
• screenshots and user-uploaded images;
• .env files or tokens;
• imported memory stores;
• personal profile facts;
• nested third-party repos such as Screenpipe, Engram, or app experiments.

The included .gitignore blocks the common private paths and file types, but still review git status before pushing.

Run the scanner before publishing changes:

npm run privacy:scan

Project Structure

.
├── bin/
│   └── open-agentmemory.command
├── docs/
│   ├── apply-local-uiux.md
│   ├── product-design-spec.md
│   ├── roadmap.md
│   ├── upstream-structure.md
│   └── viewer-patches.md
├── scripts/
│   ├── log-append.mjs
│   └── privacy-scan.mjs
├── tools/
│   ├── ensure-agentmemory-live.mjs
│   ├── import-codex-to-agentmemory.mjs
│   └── open-agentmemory.mjs
├── .gitignore
├── LOG.md
├── package.json
└── README.md

Commands

Command	Purpose
npm run start	Start Agentmemory if needed and open the dashboard.
npm run live	Ensure the local service is running.
npm run restart	Restart the local service.
npm run import:codex	Import recent Codex sessions.
npm run check	Syntax-check the helper scripts.
npm run log:append -- "message"	Append a timestamped progress or error note to LOG.md.
npm run privacy:scan	Scan tracked text files for common local secrets and private paths.

Progress Log

LOG.md is the visible maintenance ledger for this repository. Use it for:

• meaningful progress;
• checks and push status;
• errors, root cause, impact, and resolution;
• project decisions that future contributors should see.

Keep private local memory contents and machine-specific paths out of the log.

Troubleshooting

If the viewer does not open, check that the service is live:

npm run live

If Agentmemory is installed somewhere unusual, pass the CLI path:

AGENTMEMORY_CLI=/absolute/path/to/cli.mjs npm run start

If a port is already occupied, choose another base REST port:

AGENTMEMORY_URL=http://127.0.0.1:3211 npm run start

The viewer will use the base port plus 2.

Status

This is a practical local workbench and UI/UX companion for Agentmemory, not a packaged upstream fork. The scripts are usable today; the docs describe how to move the local UX improvements into the upstream source layout cleanly.