v0.1.0 · Agent with Memory

Claude's terminal, filesystem, and memory

An agent-capable MCP server with sandboxed shell access, file control, and persistent memory that survives across conversations.

$ pip install terminal-mcp-agent Copy
View Source
10
MCP Tools
5
Memory Types
∞
Conversations
0
Dependencies*
Tools
Terminal power + persistent memory
5 terminal tools for system access. 5 memory tools for context that lasts.
Terminal System Access
run_command
Execute shell commands with dangerous-command blocking
read_file
Read files from whitelisted directories
write_file
Write/overwrite files in allowed paths
list_files
Browse directories with recursive listing
run_workflow
npm install, npm run, python, or shell scripts
Memory Persistent Context
memory_store
Save a memory with name, type, tags, and content
memory_recall
Retrieve a specific memory by name
memory_search
Search memories by keyword and/or type
memory_delete
Remove a memory when it's no longer needed
memory_list
List all stored memories with the index
Memory System
Context that survives across conversations
Markdown files with YAML frontmatter. Auto-indexed. Searchable. No database needed.

user Who they are

Role, expertise, preferences. Tailor responses to the person, not the average.

feedback How to work

Corrections and confirmed approaches. Never make the same mistake twice.

project What's happening

Ongoing work, goals, deadlines. Understand the bigger picture.

reference Where to look

Pointers to external systems, dashboards, docs. Know where info lives.

note Everything else

General-purpose memory for anything worth remembering.

memory/feedback_testing.md
---
name: testing preferences
type: feedback
tags: [testing, database]
created: 2025-01-15T14:30:00
updated: 2025-01-20T09:15:00
---

Integration tests must hit a real DB.

Why: Mock/prod divergence masked a
broken migration last quarter.

How to apply: Any test touching the
data layer uses the test database.
memory/MEMORY.md
# Memory Index

## Feedback
- [testing preferences](feedback_testing.md)
  Integration tests must hit a real DB

## User
- [user role](user_role.md)
  Senior backend eng, prefers Go
Architecture
Sandboxed by design
Concentric access layers. Commands go anywhere in ROOT_DIR. File I/O is restricted. Memory lives in its own namespace.
ROOT_DIR — Full Access
run_command · list_files · run_workflow
Allowed Dirs — Read/Write
claude_playground/ + paths in path.txt
read_file write_file
Memory Store
memory/ — MEMORY.md + *.md files
memory_store memory_recall memory_search memory_delete memory_list
In Action
Claude as a system agent
You
Remember that I prefer TypeScript over JavaScript for new projects
Claude
Stored. I'll default to TypeScript when creating new files or suggesting project setups.

memory_store: "language preference" (type: feedback)
You
Set up a new Express API in my projects folder
Claude
I'll create a TypeScript Express project. Running the setup now…

run_command: mkdir -p projects/api && cd projects/api && npm init -y
run_command: npm install express typescript @types/express ts-node
write_file: projects/api/src/index.ts

Done. Created projects/api/ with Express + TypeScript, tsconfig.json, and a hello-world endpoint on port 3000.
You
What do you remember about my preferences?
Claude
Checking my memory…

I have 1 stored preference:
• language preference (feedback): You prefer TypeScript over JavaScript for new projects.
Safety
Power with guardrails
🛡

Path sandboxing

read_file and write_file are locked to whitelisted directories. Everything else is denied.

🚫

Command blocking

rm -rf /, mkfs, dd to disk, fork bombs — all blocked before they reach the shell.

🔓

Dynamic access

Edit path.txt to grant new directories. Changes take effect instantly — no restart needed.

📋

Full audit log

Every command, file read/write, and memory operation is logged with timestamps.

⚙

Env-var config

ROOT_DIR, shell, timeout, playground name — all configurable via environment variables.

🗂

File-backed memory

Plain markdown files. No database. Inspect, edit, or version-control your memory store directly.

Give Claude a terminal and a brain

Install in seconds. Persistent memory from the first conversation.

$ pip install terminal-mcp-agent Copy
View on GitHub