Timem Shell Agent

  𝓣𝓲𝓶𝓮𝓶 Ai

  ████████╗██╗███╗   ███╗███████╗███╗   ███╗
  ╚══██╔══╝██║████╗ ████║██╔════╝████╗ ████║
     ██║   ██║██╔████╔██║█████╗  ██╔████╔██║
     ██║   ██║██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║
     ██║   ██║██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║
     ╚═╝   ╚═╝╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝

  Bash   ·   Memory   ·   Time-aware

TimemAi is a lightweight local agent for everyday work. It combines an LLM conversation loop, guarded Bash command execution, and local multidimensional structured memory so it can inspect your working environment, help with files and commands, and remember useful context across sessions.

This repository packages the standalone Rust shell agent extracted from the Timem iOS workspace. It is intended for users who want to run and update the agent directly from a terminal without building the iOS app.

Layout

• agent_core/: protocol loop, provider wire-format adapters, memory/search tools, guarded local actions.
• timem_shell/: terminal UI, input editor, provider HTTP transport, audit log, CLI.
• resources/: system prompt, response protocol prompt suites, and capability manifests used by the runtime.
• docs/architecture.md: module boundaries, turn lifecycle, runtime contracts.
• docs/feature-test-management.md: feature ownership and test coverage ledger.
• .github/workflows/ci.yml: GitHub Actions workflow for push / pull request CI.

Quick Start

Install once:

cd ~/timemai
./install.sh

Use env_template as the complete config reference. Copy it to a private env file, then uncomment and edit only the values you need. The template uses export, so a plain source env makes the values visible to timem and cargo run child processes:

cp env_template env
$EDITOR env

For Aliyun/Qwen, the minimum config is:

export TIMEM_GATEWAY_PROVIDER=aliyun
export TIMEM_API_KEY=your_api_key_here
export TIMEM_MODEL=qwen-plus
export TIMEM_SPACE=.test_mem

Run:

source /path/to/your/env

timem

That is the normal installed path. timem does not load any env file implicitly; sourcing your env file makes the config visible as process env so the startup banner shows the actual effective values.

To run the newest source code directly from this checkout without reinstalling, use cargo run from the clone root. It compiles the current files and runs the debug binary:

cargo run -p timem_shell

Every env-backed setting can also be passed on the command line. See:

timem --help

Command line options override process env values.

Example without sourcing an env file:

timem \
  --data-dir data \
  --space .test_mem \
  --gateway-provider aliyun \
  --api-protocol openai-compatible \
  --model qwen-plus \
  --max-llm-input 100K \
  --bash-approval ask

Update

If you installed from a git clone, update in the same clone directory:

cd ~/timemai
git pull --ff-only
./install.sh

This rebuilds the latest release binary and overwrites the installed timem-native-rs and the timem command. Your private env file is user-managed and is not touched; source it explicitly before running:

source /path/to/your/env

If you cloned into another directory, run the same commands there. Keep your private env file wherever it is easiest for you to manage.

Quality Gates

Local production gate:

scripts/ci.sh

This runs script syntax checks, install logic tests, feature/test contract checks, sensitive scan, Rust formatting, full workspace tests, repeated edge regression, performance guard, release build, real TTY smoke, and whitespace checks.

GitHub Actions runs the same scripts/ci.sh gate on pushes and pull requests for Linux and macOS. Feature coverage is tracked in docs/feature-test-management.md; each release-ready feature is expected to have normal, boundary, error, and stress/repetition coverage or an explicit residual-risk note.

Provider Config

Common examples:

# Aliyun DashScope compatible mode
export TIMEM_GATEWAY_PROVIDER=aliyun
export TIMEM_API_KEY=...
export TIMEM_API_PROTOCOL=openai-compatible
export TIMEM_RESPONSE_PROTOCOL=markdown
export TIMEM_MAX_LLM_INPUT=100K
export TIMEM_MAX_LLM_OUTPUT=10K

# OpenAI
export TIMEM_GATEWAY_PROVIDER=openai
export TIMEM_API_KEY=...
export TIMEM_API_PROTOCOL=openai-responses

# Anthropic
export TIMEM_GATEWAY_PROVIDER=anthropic
export TIMEM_API_KEY=...
export TIMEM_API_PROTOCOL=anthropic

TIMEM_GATEWAY_PROVIDER chooses the traffic platform and default URL. TIMEM_API_PROTOCOL chooses the provider HTTP wire format. Supported values:

• openai-compatible
• openai-responses
• anthropic

openai-compatible means the Chat Completions-compatible shape (/chat/completions). openai-responses means OpenAI's Responses API shape (/responses), where output text and usage fields differ from Chat Completions.

If TIMEM_API_PROTOCOL is omitted, TIMEM_GATEWAY_PROVIDER=openai uses OpenAI Responses, TIMEM_GATEWAY_PROVIDER=anthropic uses Anthropic protocol, and other providers use OpenAI-compatible chat completions. For a custom gateway, set both TIMEM_API_PROTOCOL and TIMEM_BASE_URL explicitly.

TIMEM_RESPONSE_PROTOCOL chooses how the model must format its response for the local runtime parser. Supported values are markdown and json; the default is markdown.

TIMEM_WORK_INSTRUCTIONS controls whether Timem loads AGENTS.md and CLAUDE.md from the current working directory into agent context. Supported values are silent (default, auto-load and notify), ask, and off.

TIMEM_MAX_LLM_INPUT defaults to 100K; TIMEM_MAX_LLM_OUTPUT defaults to 10K. When observed provider input tokens plus the new prompt delta estimate reaches 90% of TIMEM_MAX_LLM_INPUT, runtime requires the model to compact dynamic prompt deltas before continuing: summarize useful dynamic context to about 10%-20% of its current token footprint, discard stale details, and place important but lengthy state into scratch memory before shrinking covered delta/slice ids. For prompt context the model can ask runtime to offload specific delta/slice ids instead of rewriting that context itself.

If a provider reports that output was cut off by the output-token limit, Timem asks whether to temporarily increase TIMEM_MAX_LLM_OUTPUT by 10K and retry the same turn. The increase only affects the current running shell process.

Inside the interactive shell, use /config to change runtime settings such as model, gateway provider, API protocol, base URL, max input/output tokens, and bash approval mode. The menu uses arrow keys and Enter, then returns to chat.

If the shell has been idle for at least 3 hours and the existing dynamic task context is over about 10K tokens, Timem asks whether to continue the previous task context. Choose YES to keep it, or NO to clear only the old dynamic prompt context and start the new question cleanly. Durable memory, chat history, scratch memory, and runtime data are not deleted by this choice.

Override the default URL only when needed:

TIMEM_BASE_URL=https://your-gateway.example/v1

Runtime Capabilities

Timem ships with built-in tool manifests, but you can overlay prompt/IDL capabilities at startup without recompiling:

export TIMEM_CAPABILITIES_DIR=/path/to/capabilities
timem

Directory layout:

capabilities/
  tools/*.yaml
  skills/<skill_id>/skill.yaml
  skills/<skill_id>/instructions.md

Runtime tool manifests may add or override canonical tool names only when they bind to an existing builtin executor such as run_bash, memmgr, shell_job_status, or capmgr, or to a command script inside the overlay directory.

Command-bound tools use this manifest shape:

kind: tool
id: my_tool
binding_type: command
binding_name: scripts/my_tool.sh
summary: My runtime tool.
description: |
  Use when this local runtime tool is appropriate.
input_properties:
  query: string
required:
  - query
example_json: |
  {
    "action": "my_tool",
    "intent": "Run my runtime tool.",
    "args": {
      "query": "hello"
    }
  }

Runtime invokes /bin/sh scripts/my_tool.sh and writes one JSON object to stdin: {"action":"my_tool","intent":"...","args":{...}}. Output is captured as an action result with bounded size and timeout.

Runtime Data

By default, runtime data is written under the directory where you start timem:

data/<space>/audit/api_audit.json
data/<space>/audit/action_audit.json
data/<space>/memory/
data/<space>/memory/shell_jobs/
data/<space>/shell_history.txt

api_audit.json is a JSON document with an events array. action_audit.json is grouped JSON for model-requested actions.

Use a fixed data root if you do not want data under the current directory:

TIMEM_DATA_DIR=/path/to/data timem

Env files are independent from runtime data. timem only reads process env, so you can keep the private env file anywhere and load it yourself:

source /path/to/your/env

Local Shell Jobs

run_bash runs short commands in the foreground. For long builds, tests, package installs, or video commands, the model can request:

{
  "action": "run_bash",
  "intent": "Run a long local task.",
  "args": {
    "command": "cargo test",
    "background": true
  }
}

Runtime returns a job_id, output file, and status file. The model should poll with shell_job_status instead of retrying the same command after a foreground timeout.

Ctrl+C is always a cancellation key, not an exit key: while editing input it cancels the current line, inside menus it cancels the current selection, and while Timem is thinking it cancels the current turn. Use Ctrl+D or /exit to leave the shell intentionally.

While Timem is thinking, you can also type an extra instruction and press Enter. That line is added to the current turn as a user_supplement prompt slice, so the next model round sees it as the newest user correction/instruction instead of waiting for a new chat turn.

Install Details

One-command install:

cd ~/timemai
./install.sh

Timem shell currently supports macOS and Linux. Windows is not supported yet. install.sh detects the OS before building:

• macOS: checks Xcode Command Line Tools and curl.
• Linux: checks cc, make, curl, and ca-certificates; when possible it installs them with apt-get, dnf, yum, pacman, or zypper.

If Rust/cargo is not installed, install.sh installs the Rust toolchain with rustup first, then builds the release binary. Cargo 1.78+ is required because the repository uses Cargo.lock v4; if an older Cargo is found and rustup exists, the installer updates the stable toolchain automatically. To disable automatic Rust install/update:

TIMEM_SHELL_SKIP_RUST_INSTALL=1 ./install.sh

If a manual cargo run fails with lock file version '4' was found, update Rust first:

rustup update stable
rustup default stable

The installer builds timem_shell, installs:

• timem-native-rs: release binary
• timem: thin wrapper that runs the binary; it does not load env files

Development Run

Use cargo run when developing the shell itself or when you want to verify the latest local source before running ./install.sh. Like timem, cargo run does not automatically load env files, so source your file or pass the needed env vars in the shell:

cd ~/timemai

TIMEM_GATEWAY_PROVIDER=aliyun \
TIMEM_API_KEY=... \
TIMEM_MODEL=qwen-plus \
TIMEM_SPACE=.test_mem \
cargo run -p timem_shell

Custom gateway example:

TIMEM_GATEWAY_PROVIDER=custom \
TIMEM_API_PROTOCOL=anthropic \
TIMEM_BASE_URL=https://your-gateway.example/v1 \
TIMEM_API_KEY=... \
TIMEM_MODEL=aws-claude-sonnet-4-6 \
TIMEM_SPACE=.test_mem \
cargo run -p timem_shell

Uninstall

Uninstall binaries:

./uninstall.sh

Private env files are user-managed and are not removed.

The uninstall script does not remove Rust. If Rust was installed only for Timem shell, remove it separately with:

rustup self uninstall

Test

cd ~/timemai
cargo fmt --check
cargo test -p agent_core
cargo test -p timem_shell

One real-provider test is intentionally ignored unless a real local key file exists.

Contributors

TimemAi is developed by limo with assistance from Claude and Codex. This line is added by myself(Timem).